chore: v2.8.8 — faster updates and lighter local runs, images attach from the chat on Windows, pet chat window

Merge branch 'perf/local-opt': faster local install and updates, lighter polling and ingest
feat: pet chat window replaces the Sagi panel; Windows pane attach no longer crashes the server
2026-10-16 10:28:58 +07:00 · 2026-10-16 10:27:26 +07:00 · 2026-10-16 10:27:22 +07:00 · 2026-10-16 10:25:32 +07:00 · 2026-10-16 10:20:59 +07:00 · 2026-10-16 10:20:59 +07:00
1108 changed files with 206504 additions and 33860 deletions
@@ -1,20 +0,0 @@
---
-name: repo-onboarding
-description: Understand this repository quickly before making changes. Use for architecture discovery, ownership mapping, command selection, and initial implementation planning.
---
-
-# Repo Onboarding Skill
-
-## Workflow
- Read `AGENTS.md`, `README.md`, and `ARCHITECTURE.md`.
- Determine target layer: `server/`, `client/`, or docs.
- Identify the minimal file set needed for the task.
- Select verification commands before editing.
-
-## Verification defaults
- Backend: `npm run test:server`
- Frontend: `npm run test:client`
-
-## References
- `references/module-map.md`
- `references/verification-map.md`
@@ -1,4 +0,0 @@
-interface:
-  display_name: "Repo Onboarding"
-  short_description: "Map architecture, ownership, and verification strategy before coding."
-  default_prompt: "Use repo-onboarding to analyze scope, affected modules, and validation commands for this task."
@@ -1,8 +0,0 @@
-# Module Map
-
- `server/index.js`: app startup and route mounting.
- `server/routes/*.js`: API contracts and route behavior.
- `server/db.js`: schema and statement layer.
- `server/websocket.js`: live update broadcast path.
- `client/src/pages/`: route-level UI.
- `client/src/components/`: reusable UI primitives.
@@ -1,8 +0,0 @@
-# Verification Map
-
- Backend changes:
-  - `npm run test:server`
- Frontend changes:
-  - `npm run test:client`
- Docs-only changes:
-  - validate command consistency against root `package.json`
@@ -1,12 +1,12 @@
 {
-  "name": "claude-code-agent-monitor-plugins",
+  "name": "agenthub",
  "description": "Official plugin marketplace for AgentHub — the `agenthub` plugin installs the dashboard itself (hooks, server, CLI), plus 10 focused plugins for analytics, cost guardrails, productivity, developer tools, AI insights, session forensics, workflow/fleet intelligence, reliability/SLOs, config & memory governance, and dashboard connectivity. Every plugin is powered by the local Agent Monitor API.",
  "owner": {
    "name": "smartgift",
    "url": "https://git.smartgift.io.vn/Smartgift-AI"
  },
-  "homepage": "https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor",
-  "repository": "https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor",
+  "homepage": "https://git.smartgift.io.vn/Smartgift-AI/AgentHub",
+  "repository": "https://git.smartgift.io.vn/Smartgift-AI/AgentHub",
  "plugins": [
    {
      "name": "agenthub",
@@ -16,61 +16,61 @@
    },
    {
      "name": "agenthub-analytics",
-      "path": "plugins/agenthub-analytics",
+      "source": "./plugins/agenthub-analytics",
      "description": "Deep analytics on Claude Code sessions — token usage (total_input/total_output/total_cache_read/total_cache_write with compaction baselines pre-summed), cost breakdowns via the pricing engine, usage trends over 365 days, cache efficiency, model mix, and productivity scoring.",
      "tags": ["analytics", "tokens", "cost", "productivity"]
    },
    {
      "name": "agenthub-cost-guard",
-      "path": "plugins/agenthub-cost-guard",
+      "source": "./plugins/agenthub-cost-guard",
      "description": "Budget guardrails — set spend limits, forecast week/month-end cost from daily trends, surface cost-threshold alerts via the alert-rule API, and quantify model-routing savings.",
      "tags": ["budget", "cost", "forecast", "alerts"]
    },
    {
      "name": "agenthub-productivity",
-      "path": "plugins/agenthub-productivity",
+      "source": "./plugins/agenthub-productivity",
      "description": "Productivity automation — daily standups, weekly/monthly reviews, sprint summaries, time-of-day focus analysis, and workflow optimization using the workflow intelligence API's 11 datasets.",
      "tags": ["productivity", "reports", "workflows", "standup"]
    },
    {
      "name": "agenthub-devtools",
-      "path": "plugins/agenthub-devtools",
+      "source": "./plugins/agenthub-devtools",
      "description": "Developer tools for the Agent Monitor — session debugging with full event-chain inspection, data-integrity inspection, event tracing, transcript search, hook diagnostics, data export (JSON/CSV/Markdown), and system health checks.",
      "tags": ["devtools", "debug", "diagnostics", "export"]
    },
    {
      "name": "agenthub-insights",
-      "path": "plugins/agenthub-insights",
+      "source": "./plugins/agenthub-insights",
      "description": "AI-powered insights — pattern detection via workflow intelligence (tool flow transitions, agent co-occurrence), anomaly alerting, trend forecasting, regression watch, benchmarking, optimization recommendations, and session comparison.",
      "tags": ["insights", "patterns", "anomaly", "optimization"]
    },
    {
      "name": "agenthub-sessions",
-      "path": "plugins/agenthub-sessions",
+      "source": "./plugins/agenthub-sessions",
      "description": "Session forensics — search by project/model/status, reconstruct event timelines, replay transcripts turn-by-turn, roll up activity per working directory, and review stale sessions before cleanup.",
      "tags": ["sessions", "search", "transcript", "replay"]
    },
    {
      "name": "agenthub-workflows",
-      "path": "plugins/agenthub-workflows",
+      "source": "./plugins/agenthub-workflows",
      "description": "Multi-agent orchestration & fleet intelligence — map the subagent DAG, audit model delegation and effectiveness, report concurrency lanes, trace error propagation by depth, and review Workflow-tool fleet runs.",
      "tags": ["workflows", "orchestration", "subagents", "fleet"]
    },
    {
      "name": "agenthub-quality",
-      "path": "plugins/agenthub-quality",
+      "source": "./plugins/agenthub-quality",
      "description": "Reliability & SLOs — scan for API errors and tool failures, audit hook delivery health (PreToolUse/PostToolUse balance), track completion/error-rate SLOs with error budgets, and alert on reliability regressions.",
      "tags": ["reliability", "errors", "slo", "quality"]
    },
    {
      "name": "agenthub-config",
-      "path": "plugins/agenthub-config",
+      "source": "./plugins/agenthub-config",
      "description": "Claude Code config & memory governance — audit skills/subagents/commands/MCP servers/hooks/settings via the Config Explorer API and curate the file-based memory store (CLAUDE.md + per-project auto-memory files).",
      "tags": ["config", "memory", "governance", "mcp"]
    },
    {
      "name": "agenthub-dashboard",
-      "path": "plugins/agenthub-dashboard",
+      "source": "./plugins/agenthub-dashboard",
      "description": "Dashboard connector — quick status checks, one-line metrics, live activity watch, and endpoint probing against the Agent Monitor API.",
      "tags": ["dashboard", "status", "connector"]
    }
@@ -5,32 +5,14 @@
    "name": "Nguyễn Ngọc Trí Vĩ",
    "url": "https://git.smartgift.io.vn/Smartgift-AI"
  },
-  "homepage": "https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor",
-  "repository": "https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor.git",
+  "homepage": "https://git.smartgift.io.vn/Smartgift-AI/AgentHub",
+  "repository": "https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git",
  "license": "MIT",
  "keywords": ["dashboard", "monitoring", "sessions", "cost", "lanes", "claude-code"],
  "commands": [
    "./plugins/agenthub/commands/agenthub-doctor.md",
    "./plugins/agenthub/commands/agenthub-update.md",
-    "./plugins/agenthub/commands/agenthub-open.md",
-    "./plugins/agenthub/commands/intake.md",
-    "./plugins/agenthub/commands/plan.md",
-    "./plugins/agenthub/commands/implement.md",
-    "./plugins/agenthub/commands/tests.md",
-    "./plugins/agenthub/commands/e2e.md",
-    "./plugins/agenthub/commands/e2e-passed.md",
-    "./plugins/agenthub/commands/review.md",
-    "./plugins/agenthub/commands/qc-plan.md",
-    "./plugins/agenthub/commands/qc.md",
-    "./plugins/agenthub/commands/gate.md",
-    "./plugins/agenthub/commands/publishing.md",
-    "./plugins/agenthub/commands/pr-open.md",
-    "./plugins/agenthub/commands/reported.md",
-    "./plugins/agenthub/commands/watching-pr.md",
-    "./plugins/agenthub/commands/merged.md",
-    "./plugins/agenthub/commands/done.md",
-    "./plugins/agenthub/commands/ship-full.md",
-    "./plugins/agenthub/commands/ship-quick.md"
+    "./plugins/agenthub/commands/agenthub-open.md"
  ],
  "hooks": {
    "PreToolUse": [
@@ -40,7 +22,8 @@
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-handler.js\" PreToolUse",
-            "timeout": 5
+            "timeout": 5,
+            "async": true
          }
        ]
      }
@@ -52,7 +35,8 @@
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-handler.js\" PostToolUse",
-            "timeout": 5
+            "timeout": 5,
+            "async": true
          }
        ]
      }
@@ -38,5 +38,9 @@
      "Bash(claude --version)",
      "Bash(gh pr *)"
    ]
+  },
+  "env": {
+    "ANTHROPIC_BASE_URL": "",
+    "ANTHROPIC_AUTH_TOKEN": ""
  }
 }
@@ -24,5 +24,4 @@ This directory contains all project-scoped Codex extensions:

 ## Included skills

- `repo-onboarding` — architecture discovery and verification selection
 - `release-guard` — release readiness checks
@@ -1,20 +0,0 @@
---
-name: repo-onboarding
-description: Understand this repository quickly before making changes. Use for architecture discovery, ownership mapping, command selection, and initial implementation planning.
---
-
-# Repo Onboarding Skill
-
-## Workflow
- Read `AGENTS.md`, `README.md`, and `ARCHITECTURE.md`.
- Determine target layer: `server/`, `client/`, or docs.
- Identify the minimal file set needed for the task.
- Select verification commands before editing.
-
-## Verification defaults
- Backend: `npm run test:server`
- Frontend: `npm run test:client`
-
-## References
- `references/module-map.md`
- `references/verification-map.md`
@@ -1,4 +0,0 @@
-interface:
-  display_name: "Repo Onboarding"
-  short_description: "Map architecture, ownership, and verification strategy before coding."
-  default_prompt: "Use repo-onboarding to analyze scope, affected modules, and validation commands for this task."
@@ -1,8 +0,0 @@
-# Module Map
-
- `server/index.js`: app startup and route mounting.
- `server/routes/*.js`: API contracts and route behavior.
- `server/db.js`: schema and statement layer.
- `server/websocket.js`: live update broadcast path.
- `client/src/pages/`: route-level UI.
- `client/src/components/`: reusable UI primitives.
@@ -1,8 +0,0 @@
-# Verification Map
-
- Backend changes:
-  - `npm run test:server`
- Frontend changes:
-  - `npm run test:client`
- Docs-only changes:
-  - validate command consistency against root `package.json`
@@ -1,7 +1,7 @@
 # Optional dev-container image for AgentHub.
-# Node 22 to match the production Dockerfile and the project's engines.
+# Node 22 to match the project's engines.
 # Adds the native-addon toolchain (better-sqlite3 builds via node-gyp) plus
-# Python 3 (statusline.py and helper scripts) and the sqlite3 CLI.
+# Python 3 (scripts/expand-ts-module-docs.py) and the sqlite3 CLI.
 #
 # This image is ONLY used by Dev Containers / Codespaces. Host-based development
 # (npm run dev / npm start) is unaffected.
@@ -22,13 +22,13 @@ dependencies (`npm run setup`).

 | Component        | Detail                                                              |
 | ---------------- | ------------------------------------------------------------------- |
-| Base image       | `mcr.microsoft.com/devcontainers/javascript-node:22` (matches prod) |
+| Base image       | `mcr.microsoft.com/devcontainers/javascript-node:22`                |
 | Native toolchain | `build-essential` + `python3` so `better-sqlite3` compiles          |
-| Python           | `python3` / `python` for `statusline.py` and helper scripts         |
+| Python           | `python3` / `python` for `scripts/expand-ts-module-docs.py`         |
 | sqlite3 CLI      | inspect the dashboard DB during development                         |
-| Features         | GitHub CLI, Docker-in-Docker (build/run the project's own Dockerfile) |
+| Features         | GitHub CLI                                                          |
 | Forwarded ports  | `4820` (server API + WebSocket), `5173` (Vite client)               |
-| Editor           | ESLint + Prettier (format on save), Vitest, Docker, YAML, Tailwind  |
+| Editor           | ESLint + Prettier (format on save), Vitest, YAML, Tailwind          |

 ## Everyday commands

@@ -4,9 +4,9 @@
  // Used only when you choose "Dev Containers: Reopen in Container" (VS Code) or
  // open the repo in a GitHub Codespace. It changes nothing for host-based dev.
  //
-  // Covers the full project: the Express server (4820), the React/Vite client
-  // (5173) and the VS Code extension. The native `better-sqlite3`
-  // addon builds here (build-essential + python3 are installed in the Dockerfile).
+  // Covers the full project: the Express server (4820) and the React/Vite
+  // client (5173). The native `better-sqlite3` addon builds here
+  // (build-essential + python3 are installed in the Dockerfile).
  //
  // NOTE (issue #193): Claude Code hooks are a HOST-side concern. This container
  // intentionally does NOT bind-mount ~/.claude and does NOT install hooks — the
@@ -20,10 +20,7 @@
  },

  "features": {
-    "ghcr.io/devcontainers/features/github-cli:1": {},
-    // Lets you build/run the project's own production Dockerfile + docker-compose
-    // from inside the dev container (e.g. to reproduce issue #193 deliberately).
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+    "ghcr.io/devcontainers/features/github-cli:1": {}
  },

  // Server (API + WebSocket) and the Vite client dev server. VS Code forwards
@@ -40,7 +37,7 @@
    }
  },

-  // Install root + client + vscode-extension deps.
+  // Install root + client deps.
  // Never installs Claude Code hooks (host-only — see note above).
  "postCreateCommand": "bash .devcontainer/post-create.sh",
  "waitFor": "postCreateCommand",
@@ -59,7 +56,6 @@
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "vitest.explorer",
-        "ms-azuretools.vscode-docker",
        "redhat.vscode-yaml",
        "yzhang.markdown-all-in-one",
        "ms-python.python",
@@ -7,7 +7,7 @@
 # @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 set -euo pipefail

-echo "▶ Installing server + client + vscode-extension dependencies (npm run setup)…"
+echo "▶ Installing server + client dependencies (npm run setup)…"
 npm run setup

 cat <<'EOF'
@@ -1,15 +0,0 @@
-node_modules/
-client/node_modules/
-client/dist/
-data/
-.git/
-.github/
-*.md
-!README.md
-images/
-wiki/
-index.html
-og-image.svg
-favicon.svg
-.prettierrc
-.prettierignore
@@ -2,6 +2,11 @@
 # Override this if your Claude Code data is in a different location, e.g.:
 #   CLAUDE_HOME=~/.codefuse/engine/cc
 # CLAUDE_HOME=~/.claude
+# A value saved from Settings (CLAUDE_HOME, CODEX_HOME, a pinned DASHBOARD_DATA_DIR)
+# goes to ~/.config/agenthub/settings.env (AGENTHUB_SETTINGS_FILE). This file wins
+# over it, and the real environment wins over both; a key set here or in the real
+# environment is reported as env-owned in Settings (a value saved there would be
+# overridden again at the next start).

 # ── Server / network ────────────────────────────────────────────────────────
 # Port to listen on (default: 4820)
@@ -66,6 +71,55 @@
 # Set to 0 to disable the poll while leaving the watcher running (default: 30000).
 #   DASHBOARD_SESSION_SYNC_MS=30000

+# Hourly database upkeep: a non-blocking WAL checkpoint (the WAL then shrinks
+# to 64 MB), PRAGMA optimize, the opt-in retention below and a bounded
+# incremental_vacuum. 0 turns it off. Never a full VACUUM (that is Settings →
+# Data → Compact, on a click).
+#   DASHBOARD_DB_MAINTAIN_MS=3600000
+
+# Automatic retention (OFF unless set): finished sessions that started more
+# than N days ago (1–3650) are purged by the hourly upkeep. Usually set from
+# Settings → Data → Session cleanup, which writes it to the settings file.
+#   AGENTHUB_RETENTION_DAYS=90
+
+# Update check interval (ms, default 3600000 = 1 h, minimum 60000). A tick
+# with no browser connected is skipped; the next browser to connect gets one.
+# DASHBOARD_UPDATE_CHECK=0 turns the scheduled check off.
+#   DASHBOARD_UPDATE_CHECK_INTERVAL_MS=3600000
+
+# Poll interval (ms) for Antigravity CLI sessions and tokens, read from agy's
+# own ~/.gemini/antigravity-cli/conversations/*.db (0 disables; default: 15000).
+#   DASHBOARD_ANTIGRAVITY_POLL_MS=15000
+# Where agy keeps its data, when not ~/.gemini (agy itself has no override).
+#   AGENTHUB_GEMINI_DIR=~/.gemini
+
+# Poll interval (ms) for Codex's rollout journals ($CODEX_HOME/sessions/**):
+# drives both the codex lane running/idle mirror and Codex sessions + tokens
+# (0 disables both; default: 15000).
+#   DASHBOARD_CODEX_POLL_MS=15000
+
+# Automatic pricing: a model seen in token usage with no rate row of its own
+# gets one from LiteLLM's public price list. 0 / false / off disables it
+# (default: enabled).
+#   AGENTHUB_PRICING_SYNC=0
+
+# The status bar's Usage panel reads Antigravity's quota by running
+# `agy --print /usage --output-format json` (no model call), which may let agy
+# update itself. 0 never runs it, and Antigravity shows no quota (default: on).
+#   AGENTHUB_AGY_USAGE=0
+
+# Heavy read-only aggregates (GET /api/workflows) run in a worker thread on
+# their own connection so they never stall other requests. 0 runs them inline
+# on the event loop instead (default: worker). A job past the timeout answers
+# 503 EREADTIMEOUT and the next one gets a fresh worker (default: 60000).
+#   AGENTHUB_READ_WORKER=0
+#   AGENTHUB_READ_TIMEOUT_MS=60000
+
+# Where settings saved from the dashboard persist (default:
+# $XDG_CONFIG_HOME/agenthub/settings.env, i.e. ~/.config/agenthub/settings.env).
+# Here or in the real environment; the file is located after this one loads.
+#   AGENTHUB_SETTINGS_FILE=/home/you/.config/agenthub/settings.env
+
 # ── Remote Data Sources (SSH multi-machine collection) ───────────────────────
 # The dashboard can pull Claude Code history from other machines over SSH:
 # it rsyncs each enabled remote's ~/.claude/projects into a sandboxed staging
@@ -94,6 +148,20 @@
 # liveness/stale sweeps (which skip them). (default: 600000 = 10min).
 #   DASHBOARD_REMOTE_ACTIVE_WINDOW_MS=600000

+# ── Privacy and push ingest (Settings → Data) ────────────────────────────────
+# All three are normally saved from Settings into the settings file; set here,
+# they are pinned and the Settings page shows them read-only.
+# Redact secrets (API keys, tokens, bearer headers, private keys, password=…)
+# from stored event payloads and summaries: 1 = on (default: off).
+#   AGENTHUB_REDACT_SECRETS=1
+# Folders whose hooks are dropped whole (and skipped by the history import and
+# the Codex reader) — absolute paths, ':'-separated (';' on Windows); a folder
+# and everything under it.
+#   AGENTHUB_IGNORE_CWD=/home/you/clients/secret:/home/you/private
+# SHA-256 (hex) of the token POST /api/hooks/ingest-batch accepts. Unset = push
+# ingest off. Settings → Data → Push ingest makes the token and stores only this.
+#   AGENTHUB_PUSH_TOKEN_SHA256=
+
 # ── Lanes (durable parallel-work units and managed git worktrees) ────────────
 # Directory dashboard-managed worktrees are provisioned under. It is also the
 # boundary safety check 2 resolves every destructive lane path against: nothing
@@ -13,13 +13,3 @@
 *.ttf binary
 *.eot binary
 *.db binary
-
-# ── GitHub Linguist overrides — keep language stats honest ──────────────────
-# wiki/mermaid.min.js is a vendored, minified third-party library (Mermaid);
-# it is not project source code and must not count toward language stats.
-wiki/mermaid.min.js linguist-vendored
-
-# wiki/i18n-content.js is machine-assembled translation data (see its header:
-# "AUTO-GENERATED wiki body-content translations ... Do not hand-edit").
-# It is a data bundle keyed by English innerHTML, not hand-written JavaScript.
-wiki/i18n-content.js linguist-generated
@@ -1,3 +0,0 @@
-#!/usr/bin/env bash
-# commit-msg hook – runs Commitlint
-npx --no-install commitlint --edit "$1"
@@ -78,3 +78,6 @@ __pycache__/

 # JetBrains IDE config — machine-specific, never shared
 .idea/
+
+# Prometheus bearer token for docker-compose.monitoring.yml (docs/MONITORING.md)
+monitoring/prometheus/dashboard-token
@@ -1,7 +1,9 @@
 #!/usr/bin/env sh
 #
-# Pre-commit: auto-format staged files, then run the full test suite.
-# The commit is ABORTED unless every test passes.
+# Pre-commit: auto-format staged files, then run the tests the commit needs —
+# both full suites for a big or risky commit, only the related tests for a
+# small one, none for docs alone (see step 2). The commit is ABORTED unless
+# every test it runs passes.
 #
 # Activated via `core.hooksPath=.husky` (set by the package.json "prepare"
 # script on `npm install`). No husky/lint-staged runtime required.
@@ -44,13 +46,13 @@ fi
 # is deterministic: it fails both runs and still blocks the commit. This keeps
 # the gate strict without making commits a dice roll on machine load.
 run_suite() {
-  # $1 = human label, $2 = npm script
+  # $1 = human label, $2 = shell command
  echo "🧪 Running $1 tests..."
-  if npm run "$2"; then
+  if sh -c "$2"; then
    return 0
  fi
  echo "⚠️  $1 suite failed — retrying once to rule out machine-load flakiness..."
-  if npm run "$2"; then
+  if sh -c "$2"; then
    echo "✅ $1 suite passed on retry — treating the first failure as a load flake."
    echo "   If this keeps happening, the flaky test above deserves a real fix."
    return 0
@@ -59,7 +61,68 @@ run_suite() {
  return 1
 }

-run_suite backend test:server
-run_suite frontend test:client
+# The frontend suite needs NODE_ENV=test: a shell exporting
+# NODE_ENV=production gets React's production build, where act() throws.
+CLIENT_FULL="NODE_ENV=test npm run test:client"

-echo "✅ Formatting applied and all tests passed — proceeding with commit."
+# How much to run. A small commit runs only the tests that touch what it
+# stages; a big or risky one runs both full suites, as does
+# AGENTHUB_FULL_TESTS=1. Docs alone (*.md, docs/) run nothing.
+#   client/ files  → `vitest related`: vitest's own import graph.
+#   anything else  → every server/__tests__ file that names the file's module
+#                    (a string match: wide on purpose, `db` reaches most).
+# ponytail: name matching misses a test that reaches a module only through
+# another one; the full run before a release still catches that.
+SMALL_MAX=10
+CODE="$(git diff --cached --name-only --diff-filter=ACMRD | grep -vE '\.md$|^docs/' || true)"
+COUNT=$(printf '%s\n' "$CODE" | grep -c . || true)
+FULL=0
+[ "${AGENTHUB_FULL_TESTS:-0}" = "1" ] && FULL=1
+[ "$COUNT" -gt "$SMALL_MAX" ] && FULL=1
+# A dependency, build/test config, this hook or a deleted file can break
+# anything, whatever imports it.
+if printf '%s\n' "$CODE" | grep -qE '(^|/)package(-lock)?\.json$|(^|/)(vite|vitest|tailwind|postcss|tsconfig)[^/]*$|^\.husky/|^scripts/test-server\.js$'; then
+  FULL=1
+fi
+if git diff --cached --name-only --diff-filter=D | grep -vE '\.md$|^docs/' | grep -q .; then
+  FULL=1
+fi
+
+if [ "$COUNT" -eq 0 ]; then
+  echo "📝 Docs only — no tests to run."
+elif [ "$FULL" = "1" ]; then
+  echo "🧪 Full run ($COUNT code files staged)."
+  run_suite backend "npm run test:server"
+  run_suite frontend "$CLIENT_FULL"
+else
+  echo "🧪 Small commit ($COUNT code files) — running the related tests only."
+  OTHER="$(printf '%s\n' "$CODE" | grep -v '^client/' || true)"
+  CLIENT="$(printf '%s\n' "$CODE" | grep '^client/' | sed 's|^client/||' || true)"
+
+  if [ -n "$OTHER" ]; then
+    RELATED="$(
+      printf '%s\n' "$OTHER" | while IFS= read -r f; do
+        case "$f" in
+          server/__tests__/*.test.js) echo "$f" ;;
+          *)
+            name="$(basename "$f")"
+            name="${name%.*}"
+            grep -lF -- "$name" server/__tests__/*.test.js 2>/dev/null || true
+            ;;
+        esac
+      done | sort -u | tr '\n' ' '
+    )"
+    if [ -n "$RELATED" ]; then
+      run_suite "backend ($(echo $RELATED | wc -w) files)" "node scripts/test-server.js $RELATED"
+    else
+      echo "⏭️  No server test names a staged file — backend skipped."
+    fi
+  fi
+
+  if [ -n "$CLIENT" ]; then
+    LIST="$(printf '%s\n' "$CLIENT" | tr '\n' ' ')"
+    run_suite "frontend (related)" "cd client && NODE_ENV=test NODE_OPTIONS=--no-experimental-webstorage npx vitest related --run --passWithNoTests $LIST"
+  fi
+fi
+
+echo "✅ Formatting applied and the tests passed — proceeding with commit."
@@ -9,17 +9,6 @@ package-lock.json
 client/package-lock.json
 .vs/
 *.md
-index.html
-wiki/index.html
 *.yml
 *.yaml
-desktop/out/
-desktop/release/
-desktop/node_modules/
-desktop/package-lock.json
-desktop/assets/*.svg
-desktop/assets/*.png
-desktop/assets/*.icns
-desktop/assets/icon.iconset/
-wiki/mermaid.min.js
-fonts/*.woff2
+server/vendor/
@@ -1,130 +0,0 @@
-# Superpowers Workspace
-
-This directory contains project-specific configuration and artifacts for the Superpowers workflow.
-
-It acts as the working memory layer for agent-driven development, enabling structured planning, execution, and iteration across sessions.
-
---
-
-## Purpose
-
-Superpowers transforms coding agents into structured, process-driven collaborators. Instead of jumping straight into code, the agent:
-
-1. Clarifies intent
-2. Produces a design
-3. Breaks work into executable steps
-4. Executes via subagents
-5. Verifies and iterates
-
-This directory stores the outputs of that workflow so progress is persistent, inspectable, and reproducible.
-
---
-
-## Directory Structure
-
-Typical contents may include:
-
-```
-.superpowers/
-├── brainstorm/        # Design explorations and refined specs
-├── plans/             # Task breakdowns and execution plans
-├── reviews/           # Code review outputs and feedback
-├── runs/              # Execution logs or agent traces
-└── README.md          # This file
-```
-
-> Exact structure may evolve depending on which skills are triggered.
-
---
-
-## Workflow Overview
-
-Superpowers operates through automatic skill activation:
-
-### 1. Brainstorming
-
-* Refines vague ideas into concrete specs
-* Explores alternatives
-* Produces structured, reviewable design docs
-
-### 2. Planning
-
-* Converts approved designs into granular tasks
-* Each task is:
-
-  * Small (2–5 min)
-  * Explicit (exact file paths + code)
-  * Verifiable
-
-### 3. Execution
-
-* Tasks are executed by subagents
-* Includes:
-
-  * Spec compliance checks
-  * Code quality review
-* Can run sequentially or in parallel
-
-### 4. Verification
-
-* Enforces test-first development (TDD)
-* Ensures correctness before completion
-* Prevents silent regressions
-
-### 5. Completion
-
-* Validates final state
-* Offers merge / PR / discard options
-* Cleans up working branches
-
---
-
-## Key Principles
-
-* **Test-first development** (RED → GREEN → REFACTOR)
-* **Small, deterministic tasks**
-* **Explicit over implicit**
-* **Process over intuition**
-* **Verification over assumption**
-
---
-
-## How to Use
-
-You don’t interact with this directory directly most of the time.
-
-Instead:
-
-* Start a task in your coding agent (Claude, Cursor, etc.)
-* Let Superpowers skills activate automatically
-* Review outputs when prompted (designs, plans, reviews)
-
-Artifacts will be written here as the workflow progresses.
-
---
-
-## When to Look Here
-
-Check this directory when you want to:
-
-* Review the current plan
-* Inspect prior design decisions
-* Debug agent behavior
-* Resume interrupted work
-* Audit what was executed
-
---
-
-## Notes
-
-* Files here are **source-of-truth for agent state**
-* Safe to commit (recommended for team workflows)
-* Avoid manual edits unless you understand the workflow implications
-
---
-
-## Related
-
-* Project root `CLAUDE.md` → global agent context
-* `.claude/` → rules, skills, and subagents
-* Superpowers upstream docs → 
@@ -1 +0,0 @@
-{"reason":"idle timeout","timestamp":1774536800234}
@@ -1 +0,0 @@
-1542
@@ -8,45 +8,14 @@
 - Correctness over cleverness.
 - Small, scoped, reversible diffs.
 - Preserve existing behavior unless change is requested.
- Update docs whenever workflow or architecture changes — follow `skills/update-project-docs/` automatically at the end of every change-set (README + VN/CN/KO mirrors, ARCHITECTURE, wiki + i18n + cache bump, server/client READMEs, docs/*).
+- Update docs whenever workflow or architecture changes — follow `skills/update-project-docs/` automatically at the end of every change-set (README.md — Vietnamese, the default — and README.en.md; docs/OVERVIEW.md + OVERVIEW.vi.md, ARCHITECTURE, wiki + i18n + cache bump, server/client READMEs, docs/*).
 - Every applicable source file you create or update (`.js/.ts/.tsx/.cjs/.mjs/.py/.sh/.css`) must start with the authorship header: a truthful file overview plus the exact line `@author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>`. See `skills/file-headers/` and `.claude/rules/file-headers.md`; verify with `bash skills/file-headers/scripts/check-headers.sh`.

-## Declare your lane stage as you work
+## Workspace stage

-This repository is watched by AgentHub, its own dashboard. A **lane** is keyed by
-working directory, and the pipeline map only moves forward when the agent doing
-the work declares its stage:
-
-```bash
-agenthub stage <stage> --tool codex --evidence "<what is actually done>"
-```
-
- Call it at every real transition — starting to plan, starting to implement,
-  running tests, opening the PR — not once at the end.
- Stage names, `default` template: `intake → plan → implement → tests → review
-  → gate → ship → done` (the 16-node `ship-feature` template accepts these as
-  aliases too; `agenthub stage` warns on stderr and names the valid nodes if a stage
-  matches none).
- **`--tool codex` matters.** One directory can back both a `claude` lane and a
-  `codex` lane, and without a tool the command fails rather than guess (it names
-  both candidates). Inside a pane the dashboard started you need nothing — that
-  pane carries `AGENTHUB_LANE_ID`, which outranks everything but `--lane`.
- If `agenthub stage` reports that no lane owns the directory, this checkout was
-  never adopted: skip the stage calls and carry on. Stage reporting is
-  reporting, never control flow — a failed `agenthub stage` never justifies skipping
-  a step of the actual work.
-
-The dashboard also *infers* your stage from your tool calls (it reads Codex's
-own rollout journals — see `docs/LANES.md#stage-detection`), and on a codex lane
-that inference does move the pipeline map forward on its own. It still never
-counts as **evidence**: a node it moved through stays amber and never renders
-green. Only your own declaration does that — which is why the call above is
-worth making even when the map already looks right.
-
-If you hold a stage for a while with no evidence recorded, the dashboard may
-type a one-line `[agenthub]` reminder straight into this pane asking you to run
-`agenthub stage ... --evidence "..."`. That is the dashboard, not the user — treat
-it as the same instruction as this section and just make the real call.
+AgentHub's `codex` workspaces — lanes in the API and CLI — (like every non-Claude AI tool workspace) carry no pipeline: the dashboard shows no stage for
+them and never infers or advances one, so there is no `agenthub stage` call to
+make while you work here as Codex.

 ## Where to work
 - `server/` for API/routes/data processing.
@@ -54,8 +23,8 @@ it as the same instruction as this section and just make the real call.
 - `scripts/` for hook/install/import/cleanup utilities.

 ## Validation expectations
- Backend changes: run `npm run test:server` when possible.
- Frontend changes: run `npm run test:client` when possible.
+- Run only the tests the change touches, never a full suite by default (full suites take 5–6 minutes): `npm run test:server -- server/__tests__/<name>.test.js`, and in `client/` `NODE_ENV=test npx vitest related <changed files> --run` (or `vitest run <test file>`). Docs-only changes run no tests.
+- Run a full suite (`npm run test:server` / `npm run test:client`) only when genuinely needed: the change touches something every screen uses (`Layout`, `Sidebar`, `StatusBar`, `tailwind.config.js`, global CSS, shared hooks/lib), a shared server core (`server/db.js`, `server/index.js`, auth/scope, middleware), a dependency or build/test config, or more than ~10 code files; or the user asks. The pre-commit hook already picks related vs. full tests per commit, so do not add an extra full run before committing.
 - If any check is skipped, report it explicitly.

 ## Safety expectations
@@ -1,67 +0,0 @@
-# Multi-stage Dockerfile for AgentHub - a Node.js server with a React client.
-# This setup optimizes the final image size by separating the build and runtime stages.
-# The first stage installs only the production dependencies for the server, while the second stage builds the React client.
-# The final stage combines the necessary files and dependencies to run the application in production.
-# Compatibility: This setup is compatible with both Podman and Docker. Runnable on any platform that supports Node.js and Alpine Linux.
-#
-# Author: Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
-
-# ── Stage 1: Install server production deps ───────────────────────────
-FROM node:22-alpine AS server-deps
-WORKDIR /app
-COPY package.json package-lock.json ./
-# The root `postinstall` hook (scripts/postinstall.js) fires during `npm ci`, so
-# the file must exist here or npm aborts with MODULE_NOT_FOUND before installing
-# anything. It self-skips when client/ is absent (as it is in this stage), so
-# copying just the one script keeps this deps-cache layer from busting on
-# unrelated scripts/ edits. Do NOT use --ignore-scripts: that would also skip
-# better-sqlite3's prebuild fetch and silently drop the native SQLite driver.
-COPY scripts/postinstall.js ./scripts/postinstall.js
-RUN npm ci --omit=dev
-
-# ── Stage 2: Build React client ───────────────────────────────────────
-FROM node:22-alpine AS client-build
-WORKDIR /app/client
-COPY client/package.json client/package-lock.json ./
-RUN npm ci
-COPY client/ ./
-# vite.config.ts stamps the UI version from the repo-root package.json (one level
-# up from the client dir). Provide it here so the built client shows the real
-# release version; the config falls back gracefully if it is ever absent.
-COPY package.json /app/package.json
-RUN npm run build
-
-# ── Stage 3: Production runtime ───────────────────────────────────────
-FROM node:22-alpine
-WORKDIR /app
-
-# Runs Claude Code sessions inside a named tmux session per lane so both the
-# dashboard (via node-pty attach) and a real terminal can share one live pane.
-RUN apk add --no-cache tmux
-
-COPY --from=server-deps /app/node_modules ./node_modules/
-COPY package.json ./
-COPY server/ ./server/
-COPY scripts/ ./scripts/
-COPY statusline/ ./statusline/
-COPY --from=client-build /app/client/dist ./client/dist/
-
-RUN mkdir -p data
-
-EXPOSE 4820
-
-ENV NODE_ENV=production
-
-# In a container the app MUST bind all interfaces: the server binds loopback by
-# default (GHSA-gr74-4xfh-6jw9), but a container's loopback is a separate
-# namespace the published port cannot reach, so a loopback bind makes the port
-# unreachable. Inside a container the trust boundary is the *host* port publish
-# (keep it on 127.0.0.1 — see docker-compose.yml / INSTALL.md), not this bind.
-ENV DASHBOARD_HOST=0.0.0.0
-
-# The recommended ~/.claude bind mount is read-only, so the server cannot write
-# its default data dir (~/.claude/agenthub). Persist to the mounted
-# volume at /app/data instead.
-ENV DASHBOARD_DATA_DIR=/app/data
-
-CMD ["node", "server/index.js"]
@@ -1,14 +1,14 @@
 # Installation

-A step-by-step guide to get AgentHub — the local control surface for Claude Code agents — up and running on your machine, with optional sections for importing history and running in a container.
+The one install-and-setup guide for AgentHub — the local control surface for Claude Code agents: the plugin install, a checkout install, configuration, the database, importing history, and troubleshooting. (`SETUP.md` is only a pointer here now.)

 ## Fastest path — install it as a Claude Code plugin

 If all you want is a working dashboard, skip every step below. From Claude Code:

 ```
-/plugin marketplace add Smartgift-AI/Claude-Code-Monitor
-/plugin install agenthub@claude-code-agent-monitor-plugins
+/plugin marketplace add https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
+/plugin install agenthub@agenthub
 ```

 The next session start installs the hooks, boots the server, puts the `agenthub` CLI
@@ -17,30 +17,157 @@ on PATH — no clone, no `npm run setup`, no
 result and `/agenthub-open` to build the UI and get the URL.

 Requires Node **>= 22.5** (a plugin install has no native `better-sqlite3`, so
-the server stores data through `node:sqlite`). Full behavior, including the
-uninstall cleanup, is in [`docs/PLUGINS.md`](docs/PLUGINS.md).
+the server stores data through `node:sqlite`), plus `git` and `tmux` from
+[Step 0](#step-0--system-packages). Full behavior, including the uninstall
+cleanup (`agenthub uninstall`), is in [`docs/PLUGINS.md`](docs/PLUGINS.md). If
+the dashboard never comes up, see
+[Plugin bootstrap never comes up](#plugin-bootstrap-never-comes-up).

 Follow the steps below instead when you want a checkout — to develop the
-dashboard, run it from source, or stay on Node 20.
+dashboard or run it from source.

 ## Requirements

 | Requirement | Version | Notes |
 |---|---|---|
-| Node.js | 20+ (22+ recommended) | Required for server and client |
+| Node.js | **22.5+** | Required for server and client (`node:sqlite`). Node 20 is end-of-life and unsupported |
 | npm | 9+ | Comes with Node.js |
 | Claude Code | 2.x+ | Required for hook integration |
-| Python | 3.6+ | Optional — statusline utility only |
-| 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` |
+| Git | Any | Cloning the repository, and every lane operation (worktrees, branch/status reads) |
+| **tmux** | 3.x (3.7+ for pane scrollbars) | **Required for the run console** — the browser terminal, `agenthub workspace shell`, and typing `/reload-plugins` into a live pane. 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 workspace ci status` |
+| Python | 3.6+ | Optional — only for `scripts/expand-ts-module-docs.py` (doc generation) |
+
+---
+
+## 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 workspace 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.
+On a native Windows install, workspace terminals are unavailable, but Settings →
+Agents still detects each AI CLI through `PATHEXT` (`claude.exe`, `codex.cmd`)
+and runs a `.cmd` updater or npm through `cmd.exe`.
+
+A terminal pane gets a draggable scrollbar only on **tmux 3.7+** — older
+versions work, just without it, and `/agenthub-doctor` warns. Homebrew ships the
+latest (`brew upgrade tmux`); Ubuntu 24.04's apt has 3.4, so build the release:
+
+```bash
+sudo apt install build-essential pkg-config libevent-dev libncurses-dev bison
+curl -fsSL https://github.com/tmux/tmux/releases/download/3.7c/tmux-3.7c.tar.gz | tar xz
+cd tmux-3.7c && ./configure && make && sudo make install   # into /usr/local/bin
+```
+
+A tmux server already running keeps its old version until every tmux session
+has closed (or the machine reboots) — only then do the scrollbars appear.
+
+Check it:
+
+```bash
+tmux -V          # e.g. tmux 3.4
+git --version
+node -v          # v22.5+ / 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, the hidden status bar and the scrollbar are set on the
+session explicitly). You can attach to the
+exact same pane from a normal terminal:
+
+```bash
+agenthub workspace 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.
+
+### macOS
+
+Status: **code-audited, untested on a Mac.** The Mac-specific paths below are
+covered by Linux-side unit tests only; the checklist at the end of this section
+is what a Mac user runs to confirm them.
+
+```bash
+brew install node git tmux       # Node >= 22.5 for the plugin install (nvm works too)
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # where the plugin puts `agenthub`
+```
+
+- **Node:** **>= 22.5** (the plugin stores data through `node:sqlite`; a
+  checkout needs the same). The `agenthub` launcher
+  pins the node that installed it and falls back to `node` on `PATH` when a
+  `brew upgrade` or `nvm` switch deletes that binary.
+- **Starts at login once you turn it on (LaunchAgent).** Off by default; with
+  Settings → About → **Start AgentHub automatically** on, the plugin bootstrap
+  installs `~/Library/LaunchAgents/io.smartgift.agenthub.plist` (a checkout:
+  the same switch, or `agenthub service install`), so the dashboard comes back after every login with no
+  Claude Code session, and launchd restarts it if it dies. Lane panes survive
+  a restart of the server. Its output goes to `~/Library/Logs/agenthub.log`.
+  A LaunchAgent needs a login at the Mac itself; over SSH only, or when
+  `launchctl` fails, the server is a detached process started by the next
+  Claude Code session (within about 10 s) or by `agenthub start`, as before. A
+  discovery entry left over from before the reboot is ignored, so a recycled
+  pid can never pass for a live dashboard.
+- **Started from a Claude Code session.** The server drops the variables that
+  describe that session (`CLAUDECODE`, `CLAUDE_CODE_SESSION_ID`,
+  `CLAUDE_PLUGIN_ROOT`, …) before anything else runs, so lane panes do not
+  inherit them. Your own configuration (`CLAUDE_CONFIG_DIR`,
+  `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_*`) passes through. A tmux server that
+  an older build started keeps its dirty global env until it exits
+  (`tmux kill-server` once, with no run you care about open).
+- **Paths.** A lane's directory is stored by its real path, so a typed `/tmp/x`
+  becomes `/private/tmp/x` and a differently-cased path on a case-insensitive
+  volume becomes the one on disk — that is what sessions report, so they bind.
+  Lanes created before this change keep the string they were created with.
+- **Account switching** uses the login Keychain item `Claude Code-credentials`;
+  macOS may ask once for permission the first time.
+- **Option key** in the browser terminal types special characters (it is not
+  sent as Meta).
+
+**Mac checklist** — please run it and report the result on issue #22:
+
+1. Fresh plugin install from a Terminal `claude` session: the dashboard answers on `http://localhost:4820`, `~/Library/LaunchAgents/io.smartgift.agenthub.plist` exists, and `/agenthub-doctor`'s launchd row says the LaunchAgent is current and running.
+2. `tmux show-environment -g | grep -i claude` prints nothing.
+3. Add a Repo lane by typing its path in a different case: sessions bind to it, and `agenthub stage plan` inside it moves the map.
+4. **Start Run** in the browser: the terminal attaches, typing works, an image paste into `claude` works, and `exit` returns to the workspace home.
+5. Changes panel: diff, stage and commit on a lane.
+6. Switch profile and check `claude /status` shows the new account. Repeat with a non-default `CLAUDE_HOME`, which also checks the Keychain service name.
+7. `brew upgrade node && brew cleanup`, then `agenthub status` still works.
+8. Reboot and log in WITHOUT opening `claude`: the dashboard answers within about 10 s (`agenthub service status` shows `state = running`).
+9. `kill <server pid>` (from `agenthub status`): it is back within a few seconds.
+10. With a lane run open, `/agenthub-update` completes, the server restarts on the new version, the plist names the new cache directory, and the run's terminal is still alive.
+11. `agenthub service uninstall`: the plist is gone and nothing restarts the server after a `kill`.

 ---

 ## Step 1 — Clone the repository

 ```bash
-git clone https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor.git
-cd Claude-Code-Monitor
+git clone https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
+cd AgentHub
 ```

 ---
@@ -48,24 +175,20 @@ cd Claude-Code-Monitor
 ## Step 2 — Install dependencies

 ```bash
-npm run setup
+npm run setup        # or: make setup
 ```

-This installs all server and client dependencies, plus the VS Code extension, and links the `agenthub` CLI.
+This runs `npm install` (whose `postinstall` hook installs the client's
+dependencies in `client/`), installs `client/` once more explicitly, and links
+the `agenthub` CLI (`npm link`; if that has no permission it prints how to link
+it by hand). A plain `npm install` is enough to build and run the dashboard —
+only the CLI link is missing.

-A plain root install already covers server **and** client — a `postinstall` hook installs the client dependencies automatically, so this alone is enough to build and run the dashboard:
+With `--ignore-scripts` the `postinstall` hook is skipped; install the client
+yourself with `npm --prefix client install`.

-```bash
-npm install
-```
-
-`npm run setup` additionally installs the VS Code extension and links the `agenthub` CLI. (If you install with `--ignore-scripts`, the `postinstall` hook is skipped — run `cd client && npm install` manually in that case.)
-
-Or via Makefile:
-
-```bash
-make setup
-```
+`better-sqlite3` gyp/compile warnings here are harmless — see
+[Troubleshooting](#better-sqlite3-errors-during-npm-install--npm-run-setup).

 ---

@@ -85,7 +208,7 @@ This starts two processes concurrently:
 Open **http://localhost:5173** in your browser.

 > [!TIP]
-> When you run the dashboard directly on the host with `npm run dev` or `npm start`, the server automatically writes the Claude Code hook configuration to `~/.claude/settings.json`. If you run the dashboard in Docker or Podman, install hooks from the host with `npm run install-hooks` after the container is up.
+> When you run the dashboard directly on the host with `npm run dev` or `npm start`, the server automatically writes the Claude Code hook configuration to `~/.claude/settings.json` — unless the `agenthub` plugin is enabled there, whose own hooks already run; then it removes any copies a checkout wrote instead, since two sets post every event twice. If you run the dashboard inside a container, install hooks from the host with `npm run install-hooks` instead — a hook path written from inside a container points at the container filesystem.

 ---

@@ -108,9 +231,9 @@ After starting a Claude Code session, you should see:
 - **Agent Board** — a `Main Agent` card in the `Waiting` column until you type your first message; it flips to `Working` on `UserPromptSubmit` / `PreToolUse` and back to `Waiting` after each `Stop`
 - **Activity Feed** — events streaming in as Claude Code uses tools
 - **Dashboard** — stats updating in real-time
- **Settings page** — model pricing rules, hook configuration status, data export and cleanup tools
+- **Settings page** — data export and cleanup tools on the Dashboard tab; Claude Code's model pricing rules, hook configuration status and CLAUDE_HOME on **Settings → Claude Code → Overview**

-If nothing appears after 30 seconds, see [SETUP.md](./SETUP.md#troubleshooting).
+If nothing appears after 30 seconds, see [Troubleshooting](#no-sessions-appearing-after-starting-claude-code).

 ### PWA install (optional)

@@ -120,61 +243,112 @@ The dashboard is a Progressive Web App. After opening it in a supported browser
 2. Once installed, the dashboard launches in its own window with no browser chrome
 3. Offline support: previously visited pages and assets are served from the Service Worker cache when the network is unavailable

-The landing page and wiki are also installable PWAs with their own manifests and service workers — visit each in a browser to install independently.
-
 ---

-## Step 5 — (Optional) Import existing Claude Code history
+## Step 5 — (Optional) Importing existing Claude Code history

-The server **automatically imports** every session under
-`~/.claude/projects/` on startup, so if you've used Claude Code on this
-machine before, your historical sessions, agents, events, token counts,
-and cost totals should already be visible in the Sessions list.
+The dashboard automatically imports sessions from `~/.claude/projects/` on
+**every startup**, so if Claude Code has been used on this machine, you'll
+see history immediately after the first launch. If you need to bring in
+history from another machine, from a backup, or just force a rescan, use
+**Settings → Import History** in the UI — it's a guided, drag-and-drop
+experience with live progress.

-To bring in history from another machine, a backup, or a `.tar.gz`
-archive a teammate sent you, use **Settings → Import History** in the
-UI. It supports three modes:
+### Pick the right mode

 ```mermaid
-flowchart LR
-    UI["Settings →<br/>Import History"] --> M1["Rescan default folder<br/>~/.claude/projects"]
-    UI --> M2["Scan a folder<br/>any absolute path"]
-    UI --> M3["Upload files<br/>.jsonl / .zip / .tar.gz / .gz"]
-    M1 --> P["Same parser as live<br/>hook ingestion"]
-    M2 --> P
-    M3 --> P
-    P --> DB[("SQLite<br/>sessions + tokens + cost")]
+flowchart TD
+    Q["Where is the history?"] --> Q1{Is it on this machine<br/>under ~/.claude/projects?}
+    Q1 -->|yes, and I just want<br/>to re-scan| M1["Mode: Rescan default folder<br/>one click"]
+    Q1 -->|yes, but in another folder<br/>on this machine| M2["Mode: Scan a folder<br/>paste the absolute path"]
+    Q1 -->|no — it's on another machine<br/>or in an archive file| M3["Mode: Upload files<br/>drag-drop JSONL or archive"]

-    style UI fill:#a855f7,stroke:#c084fc,color:#fff
-    style P fill:#f59e0b,stroke:#fbbf24,color:#000
-    style DB fill:#10b981,stroke:#34d399,color:#fff
+    M3 --> PREP["Archive source:<br/>tar -czf claude-history.tar.gz<br/>-C ~/.claude projects"]
+
+    style M1 fill:#10b981,stroke:#34d399,color:#fff
+    style M2 fill:#f59e0b,stroke:#fbbf24,color:#000
+    style M3 fill:#a855f7,stroke:#c084fc,color:#fff
 ```

-Re-imports are idempotent: sessions are deduplicated by UUID and
-compaction baselines preserve pre-compaction token totals, so running
-the importer twice never double-counts tokens or cost.
+### Step-by-step: moving history from one machine to another

-Verify it worked by opening the **Analytics** page and checking that
-per-model token totals and estimated cost look correct. Full walkthrough
-with per-OS archive commands in
-[SETUP.md → Importing existing Claude Code history](./SETUP.md#importing-existing-claude-code-history).
-### Optional: tune import limits
+**On the source machine**, bundle the projects folder:

-If you regularly import very large archives, these environment variables
-can be raised (the defaults are generous for typical use):
+```bash
+# macOS / Linux
+tar -czf claude-history.tar.gz -C ~/.claude projects

-| Variable                          | Default | Purpose                                                     |
-| --------------------------------- | ------- | ----------------------------------------------------------- |
-| `AGENTHUB_IMPORT_MAX_BYTES`           | 1 GB    | Maximum size per uploaded file                              |
-| `AGENTHUB_IMPORT_MAX_FILES`           | 2000    | Maximum files per upload request                            |
-| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES`   | 4 GB    | Ceiling on uncompressed bytes per archive (zip-bomb guard)  |
+# Windows (PowerShell, via built-in tar)
+tar -czf claude-history.tar.gz -C "$env:USERPROFILE\.claude" projects
+```

-Set them before `npm run dev` or `npm start`:
+Transfer the resulting `claude-history.tar.gz` to the destination machine
+however you like — AirDrop, `scp`, USB, cloud storage.
+
+**On the destination machine**, in the dashboard:
+
+1. Open **Settings → Import History**.
+2. Pick **Upload files** (the third tab).
+3. Drag the archive onto the drop zone.
+4. Click **Upload & Import** and watch the progress.
+5. When the green result card appears, open **Analytics → Cost** to confirm
+   per-model token totals and estimated cost.
+
+### Supported inputs
+
+Any of the following can be dropped onto the upload zone or found inside a
+folder given to **Scan a folder**:
+
+- `.jsonl` — session transcripts
+- `.meta.json` — subagent metadata sidecars
+- `.zip` — extracted with path-traversal protection
+- `.tar`, `.tar.gz`, `.tgz` — extracted via the `tar` package
+- `.gz` — single gzipped JSONL (streaming-decompressed)
+
+### Accuracy guarantees
+
+- **Idempotent** — re-importing never double-counts. Sessions are
+  deduplicated by UUID.
+- **Cost-preserving** — the `token_usage` table uses `baseline_*` columns
+  to preserve pre-compaction token totals, so re-ingesting a compacted
+  transcript never erases historical cost.
+- **Same parser as live** — `parseSessionFile` + `importSession` is the
+  single source of truth for both hook-driven ingestion and manual
+  import, so imported numbers match captured numbers exactly.
+
+### Safety
+
+Archive extraction is hardened against path traversal and archive bombs.
+The defaults are generous for real-world transcripts but tight enough to
+stop obvious attacks. If you regularly import very large archives, raise them
+before `npm run dev` or `npm start` (also listed under
+[Environment variables](#environment-variables)):
+
+| Variable                            | Default | Purpose                                                    |
+| ----------------------------------- | ------- | ---------------------------------------------------------- |
+| `AGENTHUB_IMPORT_MAX_BYTES`         | 1 GB    | Maximum size per uploaded file                             |
+| `AGENTHUB_IMPORT_MAX_FILES`         | 2000    | Maximum files per upload request                           |
+| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES` | 4 GB    | Ceiling on uncompressed bytes per archive (zip-bomb guard) |

 ```bash
 AGENTHUB_IMPORT_MAX_EXTRACT_BYTES=17179869184 npm start   # allow 16 GB extraction
 ```

+### CLI alternative
+
+For scripts and automation, the same logic runs from the terminal:
+
+```bash
+# Import (or re-import) everything under ~/.claude/projects
+npm run import-history
+
+# Dry run — show what would be imported without writing
+node scripts/import-history.js --dry-run
+
+# Scope to a single project dir
+node scripts/import-history.js --project my-project
+```
+
 ---

 ## Production mode
@@ -189,143 +363,277 @@ npm start       # Start Express serving client/dist on port 4820
 Open **http://localhost:4820** in your browser.

 `npm start` (and `agenthub start`, its backgrounded form) only run while that
-process is alive — a reboot loses it. On Linux, run the server as a systemd
-`--user` service instead so it comes back on its own after every reboot, with
-no manual step and no Claude Code (or any other tool) needed to trigger it:
+process is alive — a reboot loses it. Run the server as a systemd `--user`
+service (Linux) or a LaunchAgent (macOS) instead so it comes back on its own
+after every reboot, with no manual step and no Claude Code (or any other tool)
+needed to trigger it:

 ```bash
-agenthub service install       # writes + enables ~/.config/systemd/user/agenthub.service
-agenthub service status        # systemctl --user status agenthub
+agenthub service install       # Linux: ~/.config/systemd/user/agenthub.service
+                               # macOS: ~/Library/LaunchAgents/io.smartgift.agenthub.plist
+agenthub service status        # systemctl --user status / launchctl print
 agenthub service uninstall     # disable and remove it
 ```

-See [`README.md` → Run as a service](./README.md#run-as-a-service-auto-start-on-boot)
+See [`docs/OVERVIEW.md` → Run as a service](./docs/OVERVIEW.md#run-as-a-service-auto-start-on-boot)
 and, for plugin installs, [`docs/PLUGINS.md` → Auto-start on boot](docs/PLUGINS.md#auto-start-on-boot).

 ---

-## Optional: Agent extension packs
+## How it works

-This repository includes extension packs for both Claude Code and Codex.
+AgentHub integrates with Claude Code through its native hook system. When Claude Code performs any action (session start, tool use, turn completion, subagent finish, session exit), it fires a hook that calls a small Node.js script bundled with this project. That script forwards the event over HTTP to the dashboard server, which stores it in SQLite and broadcasts it to the browser over WebSocket.

- Claude Code loads project extensions from:
+```
+Claude Code  →  hook fires  →  hook-handler.js  →  POST /api/hooks/event
+                                                         ↓
+Browser  ←  WebSocket broadcast  ←  Express server  ←  SQLite
+```
+
+No extra Claude Code configuration is required in the normal host-run path — when you start the dashboard with `npm run dev` or `npm start`, the server configures the hooks automatically on startup (or, with the `agenthub` plugin enabled in `~/.claude/settings.json`, removes the checkout's copies — the plugin's own hooks already run, and both would post every event twice). Container deployments are the exception: after the container is up, run `npm run install-hooks` on the host so Claude Code points at `http://localhost:4820`.
+
+---
+
+## Configuration
+
+### Hook auto-installation
+
+When the dashboard is running directly on the host, the server writes the following to `~/.claude/settings.json` every time it starts:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionStart" }] }],
+    "PreToolUse":   [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PreToolUse" }] }],
+    "PostToolUse":  [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PostToolUse" }] }],
+    "Stop":         [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Stop" }] }],
+    "SubagentStop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SubagentStop" }] }],
+    "Notification": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Notification" }] }],
+    "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionEnd" }] }]
+  }
+}
+```
+
+> [!NOTE]
+> Note: `SessionStart` and `SessionEnd` hooks do not support the `matcher` field — they fire unconditionally on every session start and exit.
+
+Existing hooks in that file are preserved. The dashboard only adds or updates entries that contain `hook-handler.js`.
+
+To re-run hook installation manually:
+
+```bash
+npm run install-hooks
+```
+
+> [!TIP]
+> Container note: if you run the dashboard inside a container (a Dev Container, Codespaces, or your own image), do not install hooks from in there — the hook path a container writes points at the container filesystem, not the host. Run `npm run install-hooks` on the host instead. As a safeguard (issue #193) the installer **detects container execution and refuses to run** (exiting non-zero) so it can never poison a bind-mounted host `~/.claude`. If Claude Code itself genuinely runs inside that container, override with `AGENTHUB_ALLOW_CONTAINER_HOOKS=1 npm run install-hooks`.
+
+> [!NOTE]
+> Prefer a ready-made dev environment? This repo ships an **optional** Dev Container (`.devcontainer/`) for VS Code / GitHub Codespaces — Node 22, native build tools for `better-sqlite3`, Python, and ports `4820`/`5173` preconfigured. It's purely opt-in and changes nothing for host-based development. See [`.devcontainer/README.md`](.devcontainer/README.md). (Hooks remain host-side there too.)
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `DASHBOARD_PORT` | `4820` | Port the Express server listens on |
+| `CLAUDE_DASHBOARD_PORT` | `4820` | Port the hook handler uses when posting events to the dashboard |
+| `DASHBOARD_DB_PATH` | `data/dashboard.db` | Path to the SQLite database file |
+| `NODE_ENV` | `development` | Set to `production` to serve built client |
+| `DASHBOARD_CLIENT_DIST` | `client/dist` | Directory the built UI is served from in production. Set by the `agenthub` plugin bootstrap to its own runtime dir, because the plugin cache is replaced on every update |
+| `AGENTHUB_IMPORT_MAX_BYTES` | `1073741824` (1 GB) | Maximum size per uploaded file on `/api/import/upload` |
+| `AGENTHUB_IMPORT_MAX_FILES` | `2000` | Maximum number of files per upload request |
+| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES` | `4294967296` (4 GB) | Maximum uncompressed bytes any single archive is allowed to expand to (zip-bomb defense) |
+| `DASHBOARD_DATA_DIR` | `~/.claude/agenthub` | AgentHub's data dir; a plugin install keeps its runtime (deps, UI build, logs) in `runtime/` under it |
+
+Example with a custom port:
+
+```bash
+DASHBOARD_PORT=9000 npm run dev
+```
+
+> [!NOTE]
+> You usually do **not** need to set `DASHBOARD_PORT` manually. `npm run dev` is wrapped by `scripts/dev.js`, which probes both `127.0.0.1` and `::1` (so an SSH `LocalForward` bound to one loopback can't slip past) and picks the first free port in `4820–4859` automatically. The chosen port is propagated to the Vite dev proxy via `DASHBOARD_PORT`, and the Express server writes it to `~/.claude/.agenthub.json` so the Claude Code hook handler discovers it without any env var.
+>
+> Multiple dashboards can run side by side — for example two `npm run dev` checkouts, or `npm run dev` alongside `npm start`. Each one appends its `{port, pid, startedAt}` entry to the discovery file, and `scripts/hook-handler.js` fan-outs every hook event to every live entry, so both UIs keep their real-time stream.
+>
+> Setting `CLAUDE_DASHBOARD_PORT=N` overrides discovery entirely and forces the hook handler to a single port — useful for tests and container setups where the in-process discovery file isn't reachable from the host.
+>
+> If you bypass the picker (e.g. `npm run dev:raw`, container builds, or anything else that calls `node server/index.js` directly), make sure your client is built / proxied against the port the server actually bound.
+
+### Agent extension setup (Claude Code + Codex)
+
+This repository ships extension files for both agent ecosystems:
+
+- Claude Code:
  - `CLAUDE.md`
-  - `.claude/rules/`
-  - `skills/` (shipped as the `agenthub` plugin's skills)
-  - `agents/` (shipped as the `agenthub` plugin's agents)
- Codex project packs live under `.codex/`:
+  - `.claude/rules/*`
+  - `skills/*` (the `agenthub` plugin's own skills)
+- Codex:
  - `AGENTS.md`
-  - `.codex/rules/`
-  - `.codex/agents/`
-  - `.codex/skills/`
+  - `.codex/config.toml`
+  - `.codex/rules/default.rules`
+  - `.codex/agents/*`
+  - `.codex/skills/*`

 See [`.codex/README.md`](./.codex/README.md) for Codex extension details.

---
+### PWA configuration (optional)

-## Optional: VS Code extension
+The dashboard ships as a Progressive Web App. No configuration is required — its manifest and service worker are included out of the box.

-**AgentHub** is also available as a dedicated VS Code extension for seamless, integrated monitoring.
+**Customising the manifest:** Edit `client/public/manifest.json`. Common fields to change:

-<p align="center">
-  <img src="vscode-extension/vscode.png" alt="VS Code Extension Screenshot" width="100%">
-</p>
+- `name` / `short_name` — displayed on the home screen / dock
+- `theme_color` — address bar / title bar tint (default: `#6366f1`)
+- `background_color` — splash screen background
+- `start_url` — entry point when launched from home screen

-### Features
- **Real-time Sidebar**: Monitor agent status, health, and usage stats in the Activity Bar.
- **Pulse Status Bar**: High-level session and agent counts in the bottom status bar.
- **Direct Navigation**: Jump to specific dashboard pages or recent sessions.
- **Embedded Dashboard**: Full dashboard interface within a native VS Code tab.
+**Updating the service worker cache:** The SW has a `CACHE_NAME` constant (e.g. `dashboard-v2`). After deploying new assets, bump the version string to force browsers to re-fetch — though for the dashboard this is rarely needed: hashed `/assets/*` URLs are immutable per build, everything else is fetched network-first with cache fallback, and a `controllerchange` listener in the client reloads the page exactly once when a new SW takes over, so a rebuild propagates without a hard refresh.

-### Installation
-1. Open the [vscode-extension](./vscode-extension) folder in VS Code.
-2. Install via the Marketplace or package it manually:
-   ```bash
-   cd vscode-extension
-   npm install
-   # Generate .vsix for local install
-   npm run package
-   ```
-3. After installation, ensure the main dashboard server is running (`npm run dev`).
-4. Look for the **Radar icon** in your VS Code Activity Bar.
+**Browser support:** PWA install prompts appear in Chrome 107+, Edge 107+, and Firefox 110+ (desktop and Android). Safari supports `apple-mobile-web-app-capable` for iOS home-screen mode but does not show an install banner.

-For advanced configuration, refer to the [.vscode](./.vscode) and [vscode-extension](./vscode-extension) directories.
-
-> [!TIP]
-> Extension on VS Code Marketplace: [AgentHub](https://marketplace.visualstudio.com/items?itemName=hoangsonw.claude-code-agent-monitor)
+**Verifying PWA status:** Open DevTools → Application → Manifest to confirm the manifest loads. Check the Service Workers section to verify the SW is registered and active. The Lighthouse PWA audit should pass all core checks.

 ---

-## Container mode (Docker / Podman)
+## Database

-The repository includes both a multi-stage `Dockerfile` and a `docker-compose.yml` file. Docker and Podman are both supported.
+The SQLite database is created automatically on first run (`data/dashboard.db` in a checkout, unless `DASHBOARD_DB_PATH` says otherwise). The directory is created if it does not exist. The database uses WAL mode for concurrent reads and foreign keys for referential integrity.

-### Compose
+### Clear all data
+
+To remove all sessions, agents, events, and token usage (useful after running seed data or for a clean start):

 ```bash
-# Docker Compose
-docker compose up -d --build
-
-# Podman Compose
-CLAUDE_HOME="$HOME/.claude" podman compose up -d --build
+npm run clear-data
 ```

-Open **http://localhost:4820** in your browser.
+### Data management via Settings page

-### Plain Docker / Podman
+The Settings page (`/settings`) provides a UI for the following. **Model Pricing**
+and **Hook Configuration** are not on its Dashboard tab: they sit under the
+Claude Code tab's **Overview** (Settings → Claude Code → Overview), beside
+CLAUDE_HOME; Codex (its Overview) and Antigravity have their own pricing and
+hooks in their own tabs.
+
+- **Model Pricing** — view and edit per-model cost rates, reset to defaults, add custom models
+- **Hook Configuration** — check which hooks are installed and reinstall them
+- **Data Export** — download all sessions, agents, events, and pricing as a JSON file
+- **Session Cleanup** — abandon stale active sessions after N hours, purge old completed sessions after N days
+- **Clear All Data** — remove all sessions, agents, events, and token usage
+- **Data Management** and **About** sections render with loading placeholders while server info is being fetched, so the page is always fully navigable
+
+### Seed demo data
+
+To populate the dashboard with sample sessions, agents, and events for UI exploration:

 ```bash
-# Docker
-docker build -t agent-monitor .
-docker run -d --name agent-monitor \
-  -p 127.0.0.1:4820:4820 \
-  -v "$HOME/.claude:/root/.claude:ro" \
-  -v agent-monitor-data:/app/data \
-  agent-monitor
-
-# Podman
-podman build -t agent-monitor .
-podman run -d --name agent-monitor \
-  -p 127.0.0.1:4820:4820 \
-  -v "$HOME/.claude:/root/.claude:ro" \
-  -v "$HOME/.claude/agenthub:/app/data" \
-  agent-monitor
+npm run seed
 ```

-### Container notes
+---

-| Mount | Purpose |
-|---|---|
-| `~/.claude:/root/.claude:ro` | Lets the server import legacy Claude session history |
-| `~/.claude/agenthub:/app/data` | **Canonical SQLite database** (shared with native installs) |
+## Scripts reference

-> [!NOTE]
-> The image sets `DASHBOARD_HOST=0.0.0.0` and `DASHBOARD_DATA_DIR=/app/data` internally (baked into the `Dockerfile`). The `0.0.0.0` bind is required because a container's loopback is a separate namespace the published port cannot reach; `/app/data` is bind-mounted to `~/.claude/agenthub` on the host so Docker uses the same database as `npm start`. The trust boundary is the **host** port publish — the examples use `-p 127.0.0.1:4820:4820`, so the dashboard is local-only. To expose it on a LAN, publish on `0.0.0.0` (`-p 4820:4820`) **and** set `DASHBOARD_TOKEN`.
+| Script | Command | Description |
+|---|---|---|
+| `setup` | `npm run setup` | Install all dependencies (server + client) |
+| `dev` | `npm run dev` | Start server + client in development mode |
+| `start` | `npm start` | Start server in production mode |
+| `build` | `npm run build` | Build the React client to `client/dist/` |
+| `install-hooks` | `npm run install-hooks` | Write Claude Code hooks to `~/.claude/settings.json` |
+| `clear-data` | `npm run clear-data` | Delete all data from the database |
+| `seed` | `npm run seed` | Insert demo sessions/agents/events |
+| `import-history` | `npm run import-history` | Import legacy sessions from `~/.claude/` (also runs on startup) |
+| `claude` | Claude CLI | Uses `CLAUDE.md`, `.claude/rules`, and `.claude/skills` automatically |
+| `test` | `npm test` | Run all server and client tests |
+| `test:server` | `npm run test:server` | Run server integration tests only |
+| `test:client` | `npm run test:client` | Run client unit tests only |
+| `format` | `npm run format` | Format all files with Prettier |
+| `format:check` | `npm run format:check` | Check formatting without writing |
+
+---
+
+## Makefile targets
+
+All npm scripts are mirrored as `make` targets for convenience. Run `make help` to list them:
+
+```bash
+make help
+```
+
+Commonly used targets:
+
+| Make target | Equivalent npm command | Description |
+|---|---|---|
+| `make setup` | `npm run setup` | Install all dependencies (root + client) |
+| `make dev` | `npm run dev` | Start server + client in watch mode |
+| `make build` | `npm run build` | Build the React client for production |
+| `make start` | `npm start` | Start the production server |
+| `make prod` | `npm run build && npm start` | Build then start in one step |
+| `make test` | `npm test` | Run all tests (server + client) |
+| `make test-server` | `npm run test:server` | Run server tests only |
+| `make test-client` | `npm run test:client` | Run client tests only |
+| `make format` | `npm run format` | Format all files with Prettier |
+| `make format-check` | `npm run format:check` | Check formatting without writing |
+| `make seed` | `npm run seed` | Load demo data |
+| `make clear-data` | `npm run clear-data` | Delete all data rows |

-> [!IMPORTANT]
-> Claude Code hooks run on the host, not inside the container. After the container is healthy on `http://localhost:4820`, run `npm run install-hooks` on the host so Claude Code posts hook events back to the containerized server. The installer refuses to run inside a container (issue #193) to avoid writing a container-internal handler path into a bind-mounted `~/.claude`; use `AGENTHUB_ALLOW_CONTAINER_HOOKS=1` only if you run Claude Code inside the same container.
 ---

 ## Troubleshooting

-### `npm run setup` shows `better-sqlite3` errors
+### Plugin bootstrap never comes up

-This is expected and **non-fatal**. `better-sqlite3` is a native C++ module listed as an optional dependency. If prebuilt binaries are not available for your Node version or platform, npm will print gyp/compilation errors but still complete successfully.
+The plugin's `SessionStart` hook only checks a fast path and hands the real
+work (npm install, UI build, server start) to a detached background worker, so
+a failure there does not show in the session. When the worker's last run
+failed, the next session start prints a one-time **AgentHub:** message naming
+the log to read. Everything is logged under `~/.claude/agenthub/runtime/`:

-At runtime the server uses this fallback chain:
+| File | What it holds |
+|---|---|
+| `bootstrap.log` | Each bootstrap step and why it stopped (Node too old, install failed, superseded build, …) |
+| `npm-install.log` | npm's output for the runtime dependency install |
+| `client-build.log` | The dashboard UI build (the API still works when only this fails) |
+| `server.log` | The server's own output, when it was started detached |
+| `last-failure.json` | The last failure the session-start message reports (removed once a bootstrap succeeds) |

-1. **`better-sqlite3`** — used when prebuilt binaries are available (Node 20/22/24 on Windows x64, macOS arm64/x64, Linux x64/arm64)
-2. **`node:sqlite`** — Node.js built-in SQLite module, used automatically on Node 22+ when `better-sqlite3` is unavailable
+Then run `/agenthub-doctor` from Claude Code — it checks Node, the runtime
+dependencies, the server and the service unit, and names the fix for each
+failing row. `/agenthub-update` re-runs the bootstrap in the foreground with its
+output visible. The most common causes: Node older than 22.5 (`node -v` in the
+shell Claude Code was started from), no network or a proxy blocking the npm
+registry (`npm-install.log`), and a port held by another program (`server.log`,
+see [Port 4820 already in use](#port-4820-already-in-use)).

-If you see an error box at startup saying *"SQLite backend not available"*, either:
+### `better-sqlite3` errors during `npm install` / `npm run setup`

- **Upgrade to Node.js 22+** (recommended — zero native dependencies needed), or
- **Install build tools** so `better-sqlite3` can compile from source:
-  - **Windows:** `npm install -g windows-build-tools` or install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the C++ workload
-  - **macOS:** `xcode-select --install`
-  - **Linux:** `sudo apt install python3 make g++` (Debian/Ubuntu) or equivalent
+Only a **checkout** install sees these — the plugin installs with
+`--ignore-scripts` and never builds `better-sqlite3`. They are **harmless**:
+`better-sqlite3` is an optional dependency, and when it cannot be built npm
+skips it and the server uses Node's built-in `node:sqlite` (Node 22.5+). You do
+**not** need Python, Visual Studio Build Tools or a C++ compiler.

-  Then run: `npm rebuild better-sqlite3`
+To build it anyway (it is used when present), install a toolchain and run
+`npm rebuild better-sqlite3`:
+
+- **Windows:** [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the C++ workload
+- **macOS:** `xcode-select --install`
+- **Linux:** `sudo apt install python3 make g++` (Debian/Ubuntu) or equivalent
+
+### "SQLite backend not available" error on startup
+
+Neither `better-sqlite3` nor `node:sqlite` could be loaded — almost always a
+Node older than 22.5. Upgrade Node.
+
+### Database is locked / busy errors
+
+The SQLite database uses WAL mode with a 5-second busy timeout. If you see lock errors:
+
+- Ensure only one dashboard server instance is running
+- Check for zombie `node server/index.js` processes: `ps aux | grep server/index`
+- Delete `data/dashboard.db-wal` and `data/dashboard.db-shm` if the server was killed uncleanly, then restart

 ### `npm run dev` fails immediately

@@ -335,7 +643,7 @@ Ensure both server and client dependencies are installed:
 npm run setup
 ```

-If the error mentions a missing module like `express` or `react`, dependencies may be incomplete. Delete `node_modules` in both root and `client/`, then re-run setup:
+If the error mentions a missing module like `express` or `react`, dependencies may be incomplete. Delete `node_modules` in both the root and `client/`, then re-run setup:

 ```bash
 rm -rf node_modules client/node_modules
@@ -346,11 +654,89 @@ 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.
+**Check 1 — Is the server running?**

---
+```bash
+curl http://localhost:4820/api/health
+# Expected: {"status":"ok","timestamp":"..."}
+```
+
+**Check 2 — Are hooks installed?**
+
+With the plugin, its hooks come with it — run `/agenthub-doctor` instead. For a
+checkout, open `~/.claude/settings.json` and confirm it contains a `hooks`
+section with entries referencing `hook-handler.js`. If not, run:
+
+```bash
+npm run install-hooks
+```
+
+**Check 3 — Did you start a new Claude Code session after the server started?**
+
+Hooks only apply to sessions started after installation. Restart Claude Code.
+
+**Check 4 — Is Node.js in PATH when Claude Code runs hooks?**
+
+On some systems, the shell environment when Claude Code fires hooks may not include the full PATH. Test with:
+
+```bash
+node --version
+```
+
+If Node.js is not found, use the full path to `node` in the hook command. Edit `scripts/install-hooks.js`, replace `node` with the absolute path (e.g. `/usr/local/bin/node`), and re-run `npm run install-hooks`.
+
+### Dashboard shows "Disconnected" in the sidebar
+
+The WebSocket connection to the server failed. Ensure the server is running:
+
+```bash
+npm run dev
+```
+
+The client will automatically reconnect every 2 seconds once the server is available.
+
+### Port 4820 already in use
+
+When another program holds the port, the server stops with
+`Port 4820 is already in use by another program…` (a running AgentHub there is
+detected and simply reused). Pick another port:
+
+```bash
+DASHBOARD_PORT=4821 npm start      # or: DASHBOARD_PORT=4821 npm run dev
+```
+
+The Vite dev proxy and the Claude Code hooks follow the port on their own
+(`client/vite.config.ts` reads `DASHBOARD_PORT`; the server publishes the port it bound).
+
+And make sure Claude Code posts hooks to the new port:
+
+```bash
+CLAUDE_DASHBOARD_PORT=4821 claude
+# or edit scripts/hook-handler.js and change the default port
+```

 ## Ports

@@ -94,30 +94,6 @@ import-history: ## Import sessions from ~/.claude/ history
 clear-data: ## Delete all data rows (preserves schema)
 	node scripts/clear-data.js

-# ─── Docker / Podman ───────────────────────────────────────────────────────
-
-.PHONY: docker-build
-docker-build: ## Build dashboard Docker image
-	docker build -t claude-agent-monitor:local .
-
-.PHONY: docker-up
-docker-up: ## Start via docker-compose
-	docker compose up -d
-
-.PHONY: docker-down
-docker-down: ## Stop docker-compose stack
-	docker compose down
-
-.PHONY: docker-logs
-docker-logs: ## Tail docker-compose logs
-	docker compose logs -f
-
-
-.PHONY: podman-build
-podman-build: ## Build dashboard Podman image
-	podman build -t localhost/claude-agent-monitor:local .
-
-
 # ─── Help ───────────────────────────────────────────────────────────────────

 .PHONY: help
@@ -0,0 +1,93 @@
+# AgentHub
+
+[Tiếng Việt](README.md) · **English**
+
+A dashboard that runs on your machine to watch and drive your Claude Code (and
+Codex) sessions from the browser.
+
+| Section | Tiếng Việt |
+| --- | --- |
+| [Requirements](#requirements) | [Yêu cầu](README.md#requirements) |
+| [Option 1 — Through Claude Code](#install-claude-code) | [Cách 1 — Cài qua Claude Code](README.md#install-claude-code) |
+| [Option 2 — From a terminal](#install-terminal) | [Cách 2 — Cài bằng terminal](README.md#install-terminal) |
+| [More docs](#more-docs) | [Tài liệu thêm](README.md#more-docs) |
+
+<a id="requirements"></a>
+
+## Requirements
+
+- **Node.js ≥ 22.5**
+- **git**
+- **tmux**
+
+To install them:
+
+- Ubuntu: `sudo apt install git tmux` (get Node.js ≥ 22.5 from <https://nodejs.org>)
+- macOS: `brew install node git tmux`
+
+<a id="install-claude-code"></a>
+
+## Option 1 — Install through Claude Code (recommended)
+
+Send **each line on its own** straight into the Claude Code chat:
+
+```
+/plugin marketplace add https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
+```
+
+```
+/plugin install agenthub@agenthub
+```
+
+```
+/agenthub:agenthub-open
+```
+
+The last one prints the dashboard's address (by default <http://localhost:4820>) —
+open it in the browser and you are done.
+
+Something wrong? Send `/agenthub:agenthub-doctor` to check and fix it.
+To update to a new version: `/agenthub:agenthub-update`.
+Not using it? Quit so nothing runs in the background: **Settings → System → Quit**,
+or `agenthub stop` — opening Claude Code no longer starts it; `agenthub start` does.
+AgentHub's icon beside the clock (top bar / menu bar / notification area) offers
+**Open**, **Quit** and **Start AgentHub** too; hide it from its menu or in **Settings → System**.
+
+<a id="install-terminal"></a>
+
+## Option 2 — Install from a terminal (without Claude Code)
+
+Run these in a terminal, one after another:
+
+```bash
+git clone https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
+cd AgentHub
+npm run setup      # install the dependencies + the agenthub command
+npm run build      # build the UI
+npm start          # run the dashboard
+```
+
+Open <http://localhost:4820> in the browser.
+
+`npm start` stops when the terminal closes. To have the dashboard start every time
+the machine boots:
+
+```bash
+agenthub service install
+```
+
+> ⚠️ Pick **only one** of the two options. With both installed, every event is
+> counted twice.
+
+<a id="more-docs"></a>
+
+## More docs
+
+- Vietnamese README: [README.md](README.md)
+- The full feature overview: [docs/OVERVIEW.md](docs/OVERVIEW.md) ·
+  Tiếng Việt: [docs/OVERVIEW.vi.md](docs/OVERVIEW.vi.md)
+- Detailed install, troubleshooting: [INSTALL.md](INSTALL.md)
+- Plugin: [docs/PLUGINS.md](docs/PLUGINS.md)
+- The `agenthub` command: [docs/CLI.md](docs/CLI.md)
+
+Internal build — all rights reserved.
@@ -1,237 +1,94 @@
 # AgentHub

-Internal SmartGift build. Local-first **control surface** for Claude Code agents —
-monitoring is one part of it, not the whole. Hooks POST every tool call to an
-Express + SQLite server and a React UI updates over WebSocket; **lanes** track
-parallel agent work through a pipeline; and the `agenthub` CLI drives real terminal
-sessions, lane runtimes, and Claude Code's own configuration.
+**Tiếng Việt** · [English](README.en.md)

-AgentHub records and shows — it does not orchestrate. The session in control makes
-every decision.
+Dashboard chạy trên máy anh chị để theo dõi và điều khiển các phiên Claude Code
+(và Codex) ngay trên trình duyệt.
+
+| Phần | English |
+| --- | --- |
+| [Yêu cầu](#requirements) | [Requirements](README.en.md#requirements) |
+| [Cách 1 — Cài qua Claude Code](#install-claude-code) | [Option 1 — Through Claude Code](README.en.md#install-claude-code) |
+| [Cách 2 — Cài bằng terminal](#install-terminal) | [Option 2 — From a terminal](README.en.md#install-terminal) |
+| [Tài liệu thêm](#more-docs) | [More docs](README.en.md#more-docs) |
+
+<a id="requirements"></a>
+
+## Yêu cầu
+
+- **Node.js ≥ 22.5**
+- **git**
+- **tmux**
+
+Cài:
+
+- Ubuntu: `sudo apt install git tmux` (Node.js ≥ 22.5 tải ở <https://nodejs.org>)
+- macOS: `brew install node git tmux`
+
+<a id="install-claude-code"></a>
+
+## Cách 1 — Cài qua Claude Code (khuyên dùng)
+
+Anh chị hãy gửi **riêng từng dòng** sau thẳng vào khung chat Claude Code:
+
+```
+/plugin marketplace add https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
+```
+
+```
+/plugin install agenthub@agenthub
+```
+
+```
+/agenthub:agenthub-open
+```
+
+Dòng cuối in ra địa chỉ dashboard (mặc định <http://localhost:4820>) — mở nó
+trên trình duyệt là xong.
+
+Gặp lỗi thì gửi `/agenthub:agenthub-doctor` để tự kiểm tra và sửa.
+Cập nhật bản mới: `/agenthub:agenthub-update`.
+Không dùng thì tắt hẳn cho khỏi chạy ngầm: **Settings → Hệ thống → Thoát**, hoặc
+`agenthub stop` — mở Claude Code sẽ không tự bật lại; bật lại bằng `agenthub start`.
+Gỡ hẳn khỏi máy: **Settings → Hệ thống → Gỡ cài đặt**, hoặc `agenthub uninstall`
+(chỉ liệt kê) rồi `agenthub uninstall --yes` — xoá cả database của AgentHub; các cuộc
+trò chuyện của Claude Code/Codex, worktree và repository của bạn được giữ lại.
+Icon AgentHub cạnh đồng hồ (thanh trên cùng / menu bar / khay hệ thống) cũng có
+**Open**, **Quit** và **Start AgentHub**; ẩn nó trong menu của icon hoặc ở **Settings → Hệ thống**.
+
+<a id="install-terminal"></a>
+
+## Cách 2 — Cài bằng terminal (không qua Claude Code)
+
+Chạy lần lượt trong terminal:
+
+```bash
+git clone https://git.smartgift.io.vn/Smartgift-AI/AgentHub.git
+cd AgentHub
+npm run setup      # cài thư viện + lệnh agenthub
+npm run build      # build giao diện
+npm start          # chạy dashboard
+```
+
+Mở <http://localhost:4820> trên trình duyệt.
+
+`npm start` tắt khi đóng terminal. Muốn dashboard tự chạy mỗi lần bật máy:
+
+```bash
+agenthub service install
+```
+
+> ⚠️ Chỉ chọn **một** trong hai cách. Cài cả hai thì mỗi sự kiện bị đếm hai lần.
+
+<a id="more-docs"></a>
+
+## Tài liệu thêm
+
+- README tiếng Anh: [README.en.md](README.en.md)
+- Giới thiệu đầy đủ tính năng: [docs/OVERVIEW.vi.md](docs/OVERVIEW.vi.md) ·
+  English: [docs/OVERVIEW.md](docs/OVERVIEW.md)
+- Cài đặt chi tiết, xử lý sự cố: [INSTALL.md](INSTALL.md)
+- Plugin: [docs/PLUGINS.md](docs/PLUGINS.md)
+- Lệnh `agenthub`: [docs/CLI.md](docs/CLI.md)

 Internal build — all rights reserved.
-
-*(Tiếng Việt: [README.vi.md](README.vi.md))*
-
-## What it does
-
- **Sessions, agents, events.** Everything Claude Code emits, recorded and
-  searchable: tool calls, token usage, cost, subagent trees, transcripts.
- **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
-  that never calls `agenthub stage` still shows progress — rendered dashed amber and
-  never as done, because an inference is not evidence.
- **Run Claude Code or Codex from the browser.** A real terminal (tmux + a real
-  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.
-
-## Requirements
-
-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
-better-sqlite3 ABI mismatch and 20 client tests through a global `localStorage`
-change.
-
-The **`superpowers` plugin is required by the ship-feature pipelines only**, not
-by the dashboard. `/agenthub:ship-feature` and `/agenthub:ship-feature-lane` drive
-`superpowers:brainstorming`, `writing-plans`, `test-driven-development`,
-`requesting-code-review` and `verification-before-completion` phase by phase,
-and both built-in pipeline templates name those same slash commands as their
-per-node drivers. Without it the dashboard, hooks and CLI all work
-normally — the two pipeline skills are what stop partway. `/agenthub-doctor` reports
-it as a `WARN` row.
-
-**You do not normally have to install it.** The plugin's `SessionStart`
-bootstrap installs it for you, once, in its detached worker — so a session never
-waits on the clone, and the current session needs `/reload-plugins` before the
-skills resolve (any later session picks them up on its own). The outcome is
-logged to `~/.claude/agenthub/runtime/bootstrap.log`, and `/agenthub-update`
-retries a failed one. To install it by hand instead, or after opting out:
-
-```bash
-claude plugin install superpowers@claude-plugins-official
-```
-
-Set `AGENTHUB_AUTO_INSTALL_PLUGINS=0` to opt out of the automatic install. Only the
-plugins on a fixed allowlist in `server/lib/skill-plugins.js` are ever installed
-this way — `superpowers` today. A custom pipeline template naming some other
-plugin's command is *reported* by `/agenthub-doctor` and never installed, because a
-template is a file anyone can drop into `DASHBOARD_PIPELINES_DIR`.
-
-## Install as a Claude Code plugin
-
-Two commands on a machine that has nothing but Claude Code, no clone and no
-`npm run setup`:
-
-```
-/plugin marketplace add Smartgift-AI/Claude-Code-Monitor
-/plugin install agenthub@claude-code-agent-monitor-plugins
-```
-
-The first session start installs the hooks, boots the server, puts `agenthub` on
-PATH; it runs detached, so the session never waits on
-it. `/agenthub-doctor` reports the state, `/agenthub-open` builds the UI and prints the
-URL, `/agenthub-update` refreshes after a plugin update. This path needs Node
-**>= 22.5** (no native `better-sqlite3`, so the server uses `node:sqlite`).
-Details, including what to delete on uninstall:
-[`docs/PLUGINS.md`](docs/PLUGINS.md).
-
-## Install from a checkout
-
-```bash
-npm run setup          # root, client and vscode-extension dependencies
-npm run build          # builds the client into client/dist
-npm start              # serves the built client and the API on :4820
-```
-
-Open <http://localhost:4820>.
-
-Development, with hot reload:
-
-```bash
-npm run dev            # server on :4820, Vite client on :5173
-```
-
-`DASHBOARD_PORT` overrides the port, `DASHBOARD_CLIENT_DIST` overrides where the
-built UI is served from (defaults to `client/dist`; the plugin install points it
-at its own runtime directory). `postinstall` writes the Claude Code hook entries
-that feed the dashboard — do not run it when the `agenthub` plugin is installed, or
-every event is counted twice.
-
-### Run as a service (auto-start on boot)
-
-`npm start` only runs while that terminal (or `agenthub start`'s background
-process) is alive — a reboot loses it. On Linux, `agenthub service install` sets
-up a systemd `--user` service instead, so `:4820` is up again on its own after
-every reboot, with no manual step and no Claude Code (or any AI tool) needed
-to trigger it:
-
-```bash
-npm run build              # the service serves the built client, same as npm start
-agenthub service install       # writes + enables ~/.config/systemd/user/agenthub.service
-agenthub service status        # systemctl --user status agenthub
-agenthub service uninstall     # disable and remove it
-```
-
-`agenthub service install` also tries `loginctl enable-linger` so the service
-starts on a cold boot, before anyone logs in; if that needs elevated rights on
-your machine it prints the `sudo loginctl enable-linger <user>` command to run
-once yourself. Plugin installs get the same persistence automatically — see
-[Auto-start on boot](docs/PLUGINS.md#auto-start-on-boot) in `docs/PLUGINS.md`.
-
-## The CLI
-
-`agenthub` is linked by `npm run setup`; otherwise call `node bin/agenthub.js`.
-
-```bash
-agenthub status            # is the dashboard up
-agenthub start             # start it in the background and wait for healthy
-agenthub service install   # auto-start on boot via systemd --user (Linux)
-agenthub sessions          # recent sessions
-agenthub lanes             # lanes with stage and progress
-agenthub lanes pipeline    # this lane's pipeline template, or switch it
-agenthub lanes node <id>   # run ONE pipeline node's own command (no id: list them)
-#                        (in a session: /intake, /qc, /ship-full, /ship-quick …)
-agenthub stage <name>      # declare the current lane's stage
-agenthub tail              # live event feed
-```
-
-`agenthub --help` lists the rest.
-
-## Lanes
-
-A lane is a working directory the dashboard watches. Two kinds:
-
- **adopted** — a directory you already had. The dashboard only reads it; it is
-  never reset or deleted.
- **managed** — a git worktree the dashboard created under `LANES_ROOT`. It owns
-  the full lifecycle and may reset or remove it, behind a three-check destroy
-  guard and a counted preflight the caller has to echo back.
-
-```bash
-agenthub lanes add --cwd /path/to/repo --title "My feature"    # adopt
-agenthub lanes add --repo /path/to/repo --slug my-feature      # managed worktree
-```
-
-Every lane also carries the CLI that drives it — `claude` (the default) or
-`codex` — picked in the Add-lane modal and fixed for the life of the lane. A
-Codex lane's run panel offers Codex's own sandbox, approval and reasoning-effort
-choices, and resumes with `codex resume --last`. Codex emits none of this
-dashboard's hooks, so a Codex lane records its runs but stays absent from
-Sessions and Analytics. Its **stage detection** works anyway, from Codex's own
-rollout journals on disk (`$CODEX_HOME/sessions/**/rollout-*.jsonl`, polled every
-`DASHBOARD_CODEX_POLL_MS` ms, default 15000), and on a Codex lane a detection
-also **advances the declared stage** — the one place an inference moves the blue
-`current` ring, because a Codex session has no hook and nothing else would ever
-move it. What a Codex lane cannot get for free is *evidence*: an auto-advanced
-node stays amber (`passed-no-evidence`), never green, since only the session
-itself can say what it finished. Three things help it get there: the run console
-pre-fills a codex pane's opening prompt with a stage-declaration checklist built
-from its own pipeline nodes, `agenthub lanes agents install` writes the same
-instructions as a marker-delimited block in the lane's `AGENTS.md`, and a 60s
-sweep (`DASHBOARD_CODEX_NUDGE_MS`, `0` disables) types a one-line reminder into
-a lane's pane if its current stage sits without evidence for more than two
-minutes.
-
-The declared stage comes from `agenthub stage`. The inferred stage comes from tool
-events and expires after `DETECTION_TTL_MS` (default 5 minutes), so a lane can
-move backwards between work sessions. Detection never writes the declared stage,
-and an inferred node never renders as done.
-
-A lane's pipeline template can be switched after creation — `agenthub lanes
-pipeline <template>` from the terminal, or the pipeline-template picker next to
-the lane's title in the Workspace detail panel. Both re-resolve the lane's
-current declared stage against the new template's nodes and warn if it no
-longer matches one.
-
-A lane can also run **its own application stack**, isolated per lane, when its
-repository declares a profile at `<repo>/.agenthub/profile/` — a `profile.env` of
-declarations plus shell hooks the dashboard calls. Each lane gets a slot, and its
-ports and per-lane directories derive from it:
-
-```bash
-agenthub lanes up          # boot the stack of the lane owning this directory
-agenthub lanes runtime     # slot, ports, service health
-agenthub lanes logs api    # tail a service log
-agenthub lanes down
-```
-
-Services are fully detached, so restarting the dashboard never stops a running
-lane. This is resource namespacing on the host, not a container: lanes run as the
-same user and share the network.
-
-[`docs/LANES.md`](docs/LANES.md) has the pipeline model, the destroy guard, the
-preflight contract, the Workspace page, `GET /api/lanes/:id/git`, and the full
-runtime/profile contract.
-
-## Tests
-
-```bash
-npm run test:server    # node:test
-npm run test:client    # Vitest
-```
-
-Both must be green before a commit; the pre-commit hook runs them plus Prettier.
-
-## Layout
-
-| Path | What |
-|---|---|
-| `server/` | Express API, SQLite schema, hook ingest, lane and worktree libraries |
-| `client/` | React 18 + Vite + Tailwind dashboard |
-| `bin/agenthub.js` | CLI |
-| `docs/` | Architecture, API, lanes, database |
-| `plugins/` | Claude Code plugins shipped with the dashboard |
-
-## Docs
-
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — request flow, schema, WebSocket surface
- [`docs/LANES.md`](docs/LANES.md) — lanes, pipelines, stage detection
- [`docs/API.md`](docs/API.md) — REST endpoints (`openapi.yaml` is generated)
- [`docs/DATABASE.md`](docs/DATABASE.md) — tables and migrations
- [`INSTALL.md`](INSTALL.md)
- [`CLAUDE.md`](CLAUDE.md) — the rules an agent working in this repo must follow
@@ -1,202 +0,0 @@
-# AgentHub
-
-Bản build nội bộ SmartGift. **Bàn điều khiển** local-first cho agent Claude Code —
-monitoring chỉ là một phần, không phải tất cả. Hooks POST mỗi tool call lên server
-Express + SQLite và React UI cập nhật qua WebSocket; **lane** (làn đường) theo dõi
-công việc song song của agent qua một pipeline; còn CLI `agenthub` điều khiển phiên
-terminal thật, runtime của lane, và cả cấu hình của chính Claude Code.
-
-AgentHub ghi nhận và trình bày — nó không điều phối. Phiên đang chạy mới là nơi ra
-mọi quyết định.
-
-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ì
-
- **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.
- **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
-  session không bao giờ gọi `agenthub stage` vẫn hiển thị progress — render dạng
-  viền chấm màu hổ phách (amber) và không bao giờ hiện `done`, vì suy luận
-  không phải bằng chứng.
- **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.
-
-## Yêu cầu
-
-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`.
-
-## Cài như Claude Code plugin
-
-Hai lệnh, trên máy chỉ có Claude Code, không cần clone repo, không cần
-`npm run setup`:
-
-```
-/plugin marketplace add Smartgift-AI/Claude-Code-Monitor
-/plugin install agenthub@claude-code-agent-monitor-plugins
-```
-
-Lần session-start đầu tiên sẽ cài hooks, boot server, đưa `agenthub` vào PATH và
-chạy detached nên session không phải chờ. `/agenthub-doctor`
-báo trạng thái, `/agenthub-open` build UI và in URL, `/agenthub-update` refresh sau
-khi plugin update. Đường này cần Node **>= 22.5** (không dùng
-`better-sqlite3` native, server dùng `node:sqlite`). Chi tiết, kể cả những gì
-cần xóa lúc uninstall: [`docs/PLUGINS.md`](docs/PLUGINS.md).
-
-## Cài từ checkout
-
-```bash
-npm run setup          # cài dependency cho root, client và vscode-extension
-npm run build           # build client vào client/dist
-npm start                # serve client đã build + API trên :4820
-```
-
-Mở <http://localhost:4820>.
-
-Development, có hot reload:
-
-```bash
-npm run dev             # server trên :4820, Vite client trên :5173
-```
-
-`DASHBOARD_PORT` override port, `DASHBOARD_CLIENT_DIST` override nơi UI đã
-build được serve (mặc định `client/dist`; bản cài qua plugin trỏ vào runtime
-directory riêng của nó). `postinstall` ghi các hook entry Claude Code để nạp
-dữ liệu cho dashboard — đừng chạy nó khi plugin `agenthub` đã cài, không thì mỗi
-event bị đếm hai lần.
-
-### Chạy như một service (tự khởi động khi boot máy)
-
-`npm start` chỉ chạy khi terminal đó (hoặc tiến trình nền của `agenthub start`)
-còn sống — reboot máy là mất. Trên Linux, `agenthub service install` dựng một
-systemd `--user` service thay vào đó, để `:4820` tự động chạy lại sau mỗi lần
-reboot, không cần thao tác thủ công và không cần Claude Code (hay AI tool
-nào) để kích hoạt:
-
-```bash
-npm run build              # service serve client đã build, giống npm start
-agenthub service install       # ghi + enable ~/.config/systemd/user/agenthub.service
-agenthub service status        # systemctl --user status agenthub
-agenthub service uninstall     # disable và gỡ bỏ
-```
-
-`agenthub service install` cũng thử chạy `loginctl enable-linger` để service khởi
-động được cả khi cold boot (chưa ai login); nếu máy cần quyền cao hơn, lệnh
-này sẽ in ra `sudo loginctl enable-linger <user>` để bạn tự chạy một lần.
-Bản cài qua plugin cũng được tự khởi động tương tự — xem
-[Auto-start on boot](docs/PLUGINS.md#auto-start-on-boot) trong
-`docs/PLUGINS.md`.
-
-## CLI
-
-`agenthub` được link sẵn bởi `npm run setup`; không thì gọi `node bin/agenthub.js`.
-
-```bash
-agenthub status             # dashboard có đang chạy không
-agenthub start               # start ngầm (background) và chờ tới khi healthy
-agenthub service install     # tự khởi động khi boot máy qua systemd --user (Linux)
-agenthub sessions            # session gần đây
-agenthub lanes                # danh sách lane kèm stage và progress
-agenthub lanes pipeline      # pipeline template của lane này, hoặc đổi nó
-agenthub lanes node <id>     # chạy riêng command của MỘT node (không có id: liệt kê)
-#                          (trong session: /intake, /qc, /ship-full, /ship-quick …)
-agenthub stage <name>        # khai báo stage hiện tại của lane
-agenthub tail                 # xem live event feed
-```
-
-`agenthub --help` liệt kê phần còn lại.
-
-## Lane
-
-Lane là một working directory mà dashboard theo dõi. Hai loại:
-
- **adopted** (nhận nuôi) — một thư mục bạn đã có sẵn. Dashboard chỉ đọc nó;
-  không bao giờ reset hay xóa.
- **managed** (tự quản lý) — git worktree do dashboard tạo dưới `LANES_ROOT`.
-  Dashboard sở hữu toàn bộ vòng đời và có thể reset/xóa nó, phía sau một guard
-  ba lớp kiểm tra khi hủy (destroy guard) và một bước preflight đếm số mà bên
-  gọi phải echo lại.
-
-```bash
-agenthub lanes add --cwd /path/to/repo --title "My feature"    # adopt
-agenthub lanes add --repo /path/to/repo --slug my-feature      # managed worktree
-```
-
-Mỗi lane còn mang theo CLI điều khiển nó — `claude` (mặc định) hoặc `codex` —
-chọn trong modal Add lane và cố định suốt vòng đời của lane. Lane Codex có panel
-chạy với các lựa chọn riêng của Codex (sandbox, approval, reasoning effort) và
-resume bằng `codex resume --last`. Codex không bắn hook của dashboard này, nên
-lane Codex vẫn ghi lịch sử chạy nhưng không xuất hiện ở Sessions và Analytics.
-**Stage detection thì vẫn chạy**, đọc từ rollout journal của chính Codex trên đĩa
-(`$CODEX_HOME/sessions/**/rollout-*.jsonl`, poll mỗi `DASHBOARD_CODEX_POLL_MS` ms,
-mặc định 15000) — thứ lane Codex không tự có là stage **khai báo**, vì chỉ chính
-session đó mới gọi được `agenthub stage`.
-
-Stage khai báo (declared) đến từ `agenthub stage`. Stage suy luận (inferred) đến
-từ tool event và hết hạn sau `DETECTION_TTL_MS` (mặc định 5 phút), nên lane có
-thể lùi lại giữa các work session. Detection không bao giờ ghi đè stage khai
-báo, và node suy luận không bao giờ render thành `done`.
-
-Pipeline template của lane có thể đổi sau khi tạo — `agenthub lanes
-pipeline <template>` từ terminal, hoặc dùng picker chọn pipeline-template
-cạnh tiêu đề lane trong panel chi tiết của trang Workspace. Cả hai đều
-re-resolve lại stage đã khai báo hiện tại của lane theo node-list của template
-mới, và cảnh báo nếu nó không còn khớp node nào.
-
-Lane cũng có thể chạy **application stack riêng của nó**, cô lập theo từng
-lane, khi repository của nó khai báo một profile tại `<repo>/.agenthub/profile/`
-— một file `profile.env` khai báo cộng shell hooks mà dashboard gọi. Mỗi lane
-được cấp một slot, port và thư mục riêng theo lane được suy ra từ đó:
-
-```bash
-agenthub lanes up            # boot stack của lane sở hữu thư mục hiện tại
-agenthub lanes runtime       # slot, port, tình trạng service
-agenthub lanes logs api      # tail log của một service
-agenthub lanes down
-```
-
-Service chạy hoàn toàn detached, nên restart dashboard không bao giờ dừng
-lane đang chạy. Đây là namespacing tài nguyên trên host, không phải
-container: các lane chạy chung user và share network.
-
-[`docs/LANES.md`](docs/LANES.md) có mô hình pipeline, destroy guard, hợp đồng
-(contract) preflight, trang Workspace, `GET /api/lanes/:id/git`, và toàn bộ
-hợp đồng runtime/profile.
-
-## Test
-
-```bash
-npm run test:server    # node:test
-npm run test:client    # Vitest
-```
-
-Cả hai phải xanh (pass) trước khi commit; pre-commit hook chạy chúng cộng
-thêm Prettier.
-
-## Cấu trúc thư mục
-
-| Đường dẫn | Là gì |
-|---|---|
-| `server/` | Express API, schema SQLite, hook ingest, thư viện lane và worktree |
-| `client/` | Dashboard React 18 + Vite + Tailwind |
-| `bin/agenthub.js` | CLI |
-| `docs/` | Architecture, API, lanes, database |
-| `plugins/` | Các Claude Code plugin đi kèm dashboard |
-
-## Tài liệu
-
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — luồng request, schema, bề mặt WebSocket
- [`docs/LANES.md`](docs/LANES.md) — lane, pipeline, stage detection
- [`docs/API.md`](docs/API.md) — REST endpoint (`openapi.yaml` được generate tự động)
- [`docs/DATABASE.md`](docs/DATABASE.md) — bảng và migration
- [`INSTALL.md`](INSTALL.md)
- [`CLAUDE.md`](CLAUDE.md) — quy tắc agent làm việc trong repo này phải tuân theo
@@ -1,499 +1,14 @@
 # Setup Guide

-A comprehensive guide to setting up and configuring the Agent Dashboard, including how it integrates with Claude Code, environment variables, container deployment, and troubleshooting common issues.
-
-## How it works
-
-Agent Dashboard integrates with Claude Code through its native hook system. When Claude Code performs any action (session start, tool use, turn completion, subagent finish, session exit), it fires a hook that calls a small Node.js script bundled with this project. That script forwards the event over HTTP to the dashboard server, which stores it in SQLite and broadcasts it to the browser over WebSocket.
-
-```
-Claude Code  →  hook fires  →  hook-handler.js  →  POST /api/hooks/event
-                                                         ↓
-Browser  ←  WebSocket broadcast  ←  Express server  ←  SQLite
-```
-
-No extra Claude Code configuration is required in the normal host-run path — when you start the dashboard with `npm run dev` or `npm start`, the server configures the hooks automatically on startup. Container deployments are the exception: after the container is up, run `npm run install-hooks` on the host so Claude Code points at `http://localhost:4820`.
-
---
-
-## Configuration
-
-### Hook auto-installation
-
-When the dashboard is running directly on the host, the server writes the following to `~/.claude/settings.json` every time it starts:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionStart" }] }],
-    "PreToolUse":   [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PreToolUse" }] }],
-    "PostToolUse":  [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PostToolUse" }] }],
-    "Stop":         [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Stop" }] }],
-    "SubagentStop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SubagentStop" }] }],
-    "Notification": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Notification" }] }],
-    "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionEnd" }] }]
-  }
-}
-```
-
-> [!NOTE]
-> Note: `SessionStart` and `SessionEnd` hooks do not support the `matcher` field — they fire unconditionally on every session start and exit.
-
-Existing hooks in that file are preserved. The dashboard only adds or updates entries that contain `hook-handler.js`.
-
-To re-run hook installation manually:
-
-```bash
-npm run install-hooks
-```
-
-> [!TIP]
-> Container note: do not rely on hook auto-install from inside Docker or Podman. The hook path written by a container would point at the container filesystem, not the host. Start the container first, then run `npm run install-hooks` on the host. As a safeguard (issue #193), the installer now **detects container execution and refuses to run** (exiting non-zero) so it can never poison a bind-mounted host `~/.claude`; the containerized server logs the same guidance instead of silently writing a bad path. If you genuinely run Claude Code inside the same container, override with `AGENTHUB_ALLOW_CONTAINER_HOOKS=1 npm run install-hooks`.
-
-> [!NOTE]
-> Prefer a ready-made dev environment? This repo ships an **optional** Dev Container (`.devcontainer/`) for VS Code / GitHub Codespaces — Node 22, native build tools for `better-sqlite3`, Python, and ports `4820`/`5173` preconfigured. It's purely opt-in and changes nothing for host-based development. See [`.devcontainer/README.md`](.devcontainer/README.md). (Hooks remain host-side there too.)
-
-### Container runtime (Docker / Podman)
-
-The repo includes both a multi-stage `Dockerfile` and a `docker-compose.yml` file. The container image serves the built client and API on port `4820`, stores SQLite data under `/app/data`, and can import legacy Claude history from a read-only `~/.claude` mount.
-
-```bash
-# Docker Compose
-docker compose up -d --build
-
-# Podman Compose
-CLAUDE_HOME="$HOME/.claude" podman compose up -d --build
-
-# Plain Docker
-docker build -t agent-monitor .
-docker run -d --name agent-monitor \
-  -p 127.0.0.1:4820:4820 \
-  -v "$HOME/.claude:/root/.claude:ro" \
-  -v agent-monitor-data:/app/data \
-  agent-monitor
-
-# Plain Podman
-podman build -t agent-monitor .
-podman run -d --name agent-monitor \
-  -p 127.0.0.1:4820:4820 \
-  -v "$HOME/.claude:/root/.claude:ro" \
-  -v "$HOME/.claude/agenthub:/app/data" \
-  agent-monitor
-```
-
-Container-specific behavior:
-
- The dashboard is available at `http://localhost:4820`
- The image sets `DASHBOARD_HOST=0.0.0.0` (bind inside the container — its loopback is a separate namespace the published port cannot reach) and `DASHBOARD_DATA_DIR=/app/data` internally; both are baked into the `Dockerfile`
- The examples publish on `127.0.0.1` only, so the dashboard is local-only. To expose it on a LAN, publish on `0.0.0.0` (`-p 4820:4820`) **and** set `DASHBOARD_TOKEN`
- `~/.claude:/root/.claude:ro` is used for history import only
- `~/.claude/agenthub:/app/data` is the **canonical** SQLite database (shared with native installs)
- Claude Code hooks still execute on the host, so install them from the host with `npm run install-hooks`
-
-### Environment variables
-
-| Variable | Default | Description |
-|---|---|---|
-| `DASHBOARD_PORT` | `4820` | Port the Express server listens on |
-| `CLAUDE_DASHBOARD_PORT` | `4820` | Port the hook handler uses when posting events to the dashboard |
-| `DASHBOARD_DB_PATH` | `data/dashboard.db` | Path to the SQLite database file |
-| `NODE_ENV` | `development` | Set to `production` to serve built client |
-| `DASHBOARD_CLIENT_DIST` | `client/dist` | Directory the built UI is served from in production. Set by the `agenthub` plugin bootstrap to its own runtime dir, because the plugin cache is replaced on every update |
-| `AGENTHUB_IMPORT_MAX_BYTES` | `1073741824` (1 GB) | Maximum size per uploaded file on `/api/import/upload` |
-| `AGENTHUB_IMPORT_MAX_FILES` | `2000` | Maximum number of files per upload request |
-| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES` | `4294967296` (4 GB) | Maximum uncompressed bytes any single archive is allowed to expand to (zip-bomb defense) |
-
-Example with a custom port:
-
-```bash
-DASHBOARD_PORT=9000 npm run dev
-```
-
-> [!NOTE]
-> You usually do **not** need to set `DASHBOARD_PORT` manually. `npm run dev` is wrapped by `scripts/dev.js`, which probes both `127.0.0.1` and `::1` (so an SSH `LocalForward` bound to one loopback can't slip past) and picks the first free port in `4820–4859` automatically. The chosen port is propagated to the Vite dev proxy via `DASHBOARD_PORT`, and the Express server writes it to `~/.claude/.agenthub.json` so the Claude Code hook handler discovers it without any env var.
->
-> Multiple dashboards can run side by side — for example two `npm run dev` checkouts, or `npm run dev` alongside `npm start`. Each one appends its `{port, pid, startedAt}` entry to the discovery file, and `scripts/hook-handler.js` fan-outs every hook event to every live entry, so both UIs keep their real-time stream.
->
-> Setting `CLAUDE_DASHBOARD_PORT=N` overrides discovery entirely and forces the hook handler to a single port — useful for tests and container setups where the in-process discovery file isn't reachable from the host.
->
-> If you bypass the picker (e.g. `npm run dev:raw`, container builds, or anything else that calls `node server/index.js` directly), make sure your client is built / proxied against the port the server actually bound.
-
-### Agent extension setup (Claude Code + Codex)
-
-This repository ships extension files for both agent ecosystems:
-
- Claude Code:
-  - `CLAUDE.md`
-  - `.claude/rules/*`
-  - `skills/*` (the `agenthub` plugin's own skills)
-  - `agents/*` (the `agenthub` plugin's own agents)
- Codex:
-  - `AGENTS.md`
-  - `.codex/config.toml`
-  - `.codex/rules/default.rules`
-  - `.codex/agents/*`
-  - `.codex/skills/*`
-
-See [`.codex/README.md`](./.codex/README.md) for Codex extension details.
-
-### VS Code extension setup
-
-**AgentHub** is available as an integrated VS Code extension for seamless monitoring within your editor.
-
- **Activity Bar View**: Adds a custom "Radar" icon to the activity bar providing real-time agent health, token counts, and session stats.
- **Status Bar Integration**: Displays live session and agent pulse counts in the bottom bar.
- **Embedded Dashboard**: Renders the full web dashboard directly in a VS Code editor tab.
- **Automated Detection**: Automatically finds your dashboard server on ports `5173` or `4820`.
-
-<p align="center">
-  <img src="vscode-extension/vscode.png" alt="VS Code Extension Screenshot" width="100%">
-</p>
-
-To install or develop the extension:
-1. Open the [vscode-extension](./vscode-extension) directory in VS Code.
-2. Run `npm install` and `npm run package` to generate a local `.vsix` installer.
-3. For developer details, see [vscode-extension/README.md](./vscode-extension/README.md).
-
-> [!TIP]
-> Extension on VS Code Marketplace: [AgentHub](https://marketplace.visualstudio.com/items?itemName=hoangsonw.claude-code-agent-monitor)
-
-### PWA configuration (optional)
-
-The dashboard, landing page, and wiki each ship as independent Progressive Web Apps. No configuration is required — manifests and service workers are included out of the box.
-
-**Customising the manifest:** Edit the `manifest.json` in the relevant directory (`client/public/` for dashboard, root for landing, `wiki/` for wiki). Common fields to change:
-
- `name` / `short_name` — displayed on the home screen / dock
- `theme_color` — address bar / title bar tint (default: `#6366f1`)
- `background_color` — splash screen background
- `start_url` — entry point when launched from home screen
-
-**Updating the service worker cache:** Each SW has a `CACHE_NAME` constant (e.g. `dashboard-v2`). After deploying new assets, bump the version string to force browsers to re-fetch — though for the dashboard this is rarely needed: hashed `/assets/*` URLs are immutable per build, everything else is fetched network-first with cache fallback, and a `controllerchange` listener in the client reloads the page exactly once when a new SW takes over, so a rebuild propagates without a hard refresh.
-
-**Browser support:** PWA install prompts appear in Chrome 107+, Edge 107+, and Firefox 110+ (desktop and Android). Safari supports `apple-mobile-web-app-capable` for iOS home-screen mode but does not show an install banner.
-
-**Verifying PWA status:** Open DevTools → Application → Manifest to confirm the manifest loads. Check the Service Workers section to verify the SW is registered and active. The Lighthouse PWA audit should pass all core checks.
-
---
-
-## Database
-
-The SQLite database is created automatically at `data/dashboard.db` on first run. The directory is created if it does not exist. The database uses WAL mode for concurrent reads and foreign keys for referential integrity.
-
-### Clear all data
-
-To remove all sessions, agents, events, and token usage (useful after running seed data or for a clean start):
-
-```bash
-npm run clear-data
-```
-
-### Data management via Settings page
-
-The Settings page (`/settings`) provides a UI for:
-
- **Model Pricing** — view and edit per-model cost rates, reset to defaults, add custom models
- **Hook Configuration** — check which hooks are installed and reinstall them
- **Data Export** — download all sessions, agents, events, and pricing as a JSON file
- **Session Cleanup** — abandon stale active sessions after N hours, purge old completed sessions after N days
- **Clear All Data** — remove all sessions, agents, events, and token usage
- **Data Management** and **About** sections render with loading placeholders while server info is being fetched, so the page is always fully navigable
-
-### Seed demo data
-
-To populate the dashboard with sample sessions, agents, and events for UI exploration:
-
-```bash
-npm run seed
-```
-
---
-
-## Importing existing Claude Code history
-
-The dashboard automatically imports sessions from `~/.claude/projects/` on
-**every startup**, so if Claude Code has been used on this machine, you'll
-see history immediately after the first launch. If you need to bring in
-history from another machine, from a backup, or just force a rescan, use
-**Settings → Import History** in the UI — it's a guided, drag-and-drop
-experience with live progress.
-### Pick the right mode
-
-```mermaid
-flowchart TD
-    Q["Where is the history?"] --> Q1{Is it on this machine<br/>under ~/.claude/projects?}
-    Q1 -->|yes, and I just want<br/>to re-scan| M1["Mode: Rescan default folder<br/>one click"]
-    Q1 -->|yes, but in another folder<br/>on this machine| M2["Mode: Scan a folder<br/>paste the absolute path"]
-    Q1 -->|no — it's on another machine<br/>or in an archive file| M3["Mode: Upload files<br/>drag-drop JSONL or archive"]
-
-    M3 --> PREP["Archive source:<br/>tar -czf claude-history.tar.gz<br/>-C ~/.claude projects"]
-
-    style M1 fill:#10b981,stroke:#34d399,color:#fff
-    style M2 fill:#f59e0b,stroke:#fbbf24,color:#000
-    style M3 fill:#a855f7,stroke:#c084fc,color:#fff
-```
-
-### Step-by-step: moving history from one machine to another
-
-**On the source machine**, bundle the projects folder:
-
-```bash
-# macOS / Linux
-tar -czf claude-history.tar.gz -C ~/.claude projects
-
-# Windows (PowerShell, via built-in tar)
-tar -czf claude-history.tar.gz -C "$env:USERPROFILE\.claude" projects
-```
-
-Transfer the resulting `claude-history.tar.gz` to the destination machine
-however you like — AirDrop, `scp`, USB, cloud storage.
-
-**On the destination machine**, in the dashboard:
-
-1. Open **Settings → Import History**.
-2. Pick **Upload files** (the third tab).
-3. Drag the archive onto the drop zone.
-4. Click **Upload & Import** and watch the progress.
-5. When the green result card appears, open **Analytics → Cost** to confirm
-   per-model token totals and estimated cost.
-
-### Supported inputs
-
-Any of the following can be dropped onto the upload zone or found inside a
-folder given to **Scan a folder**:
-
- `.jsonl` — session transcripts
- `.meta.json` — subagent metadata sidecars
- `.zip` — extracted with path-traversal protection
- `.tar`, `.tar.gz`, `.tgz` — extracted via the `tar` package
- `.gz` — single gzipped JSONL (streaming-decompressed)
-
-### Accuracy guarantees
-
- **Idempotent** — re-importing never double-counts. Sessions are
-  deduplicated by UUID.
- **Cost-preserving** — the `token_usage` table uses `baseline_*` columns
-  to preserve pre-compaction token totals, so re-ingesting a compacted
-  transcript never erases historical cost.
- **Same parser as live** — `parseSessionFile` + `importSession` is the
-  single source of truth for both hook-driven ingestion and manual
-  import, so imported numbers match captured numbers exactly.
-
-### Safety
-
-Archive extraction is hardened against path traversal and archive bombs.
-The defaults are generous for real-world transcripts but tight enough to
-stop obvious attacks; see the env vars table above for
-`AGENTHUB_IMPORT_MAX_BYTES`, `AGENTHUB_IMPORT_MAX_FILES`, and
-`AGENTHUB_IMPORT_MAX_EXTRACT_BYTES`.
-
-### CLI alternative
-
-For scripts and automation, the same logic runs from the terminal:
-
-```bash
-# Import (or re-import) everything under ~/.claude/projects
-npm run import-history
-
-# Dry run — show what would be imported without writing
-node scripts/import-history.js --dry-run
-
-# Scope to a single project dir
-node scripts/import-history.js --project my-project
-```
-
---
-
-## Scripts reference
-
-| Script | Command | Description |
-|---|---|---|
-| `setup` | `npm run setup` | Install all dependencies (server + client) |
-| `dev` | `npm run dev` | Start server + client in development mode |
-| `start` | `npm start` | Start server in production mode |
-| `build` | `npm run build` | Build the React client to `client/dist/` |
-| `install-hooks` | `npm run install-hooks` | Write Claude Code hooks to `~/.claude/settings.json` |
-| `clear-data` | `npm run clear-data` | Delete all data from the database |
-| `seed` | `npm run seed` | Insert demo sessions/agents/events |
-| `import-history` | `npm run import-history` | Import legacy sessions from `~/.claude/` (also runs on startup) |
-| `claude` | Claude CLI | Uses `CLAUDE.md`, `.claude/rules`, and `.claude/skills` automatically |
-| `test` | `npm test` | Run all server and client tests |
-| `test:server` | `npm run test:server` | Run server integration tests only |
-| `test:client` | `npm run test:client` | Run client unit tests only |
-| `format` | `npm run format` | Format all files with Prettier |
-| `format:check` | `npm run format:check` | Check formatting without writing |
-
---
-
-## Makefile targets
-
-All npm scripts are mirrored as `make` targets for convenience. Run `make help` to list them:
-
-```bash
-make help
-```
-
-Commonly used targets:
-
-| Make target | Equivalent npm command | Description |
-|---|---|---|
-| `make setup` | `npm run setup` | Install all dependencies (root + client) |
-| `make dev` | `npm run dev` | Start server + client in watch mode |
-| `make build` | `npm run build` | Build the React client for production |
-| `make start` | `npm start` | Start the production server |
-| `make prod` | `npm run build && npm start` | Build then start in one step |
-| `make test` | `npm test` | Run all tests (server + client) |
-| `make test-server` | `npm run test:server` | Run server tests only |
-| `make test-client` | `npm run test:client` | Run client tests only |
-| `make format` | `npm run format` | Format all files with Prettier |
-| `make format-check` | `npm run format:check` | Check formatting without writing |
-| `make seed` | `npm run seed` | Load demo data |
-| `make clear-data` | `npm run clear-data` | Delete all data rows |
-| `make docker-up` | `docker compose up -d` | Start via docker-compose |
-| `make docker-down` | `docker compose down` | Stop docker-compose stack |
-
---
-
-## Statusline (optional)
-
-The `statusline/` directory contains a standalone terminal statusline for Claude Code showing model, working directory, git branch, context window usage, and token counts. It is independent of the web dashboard.
-
-See [statusline/README.md](./statusline/README.md) for installation instructions.
-
---
-
-## Troubleshooting
-
-### `better-sqlite3` errors during `npm install` / `npm run setup`
-
-These warnings are **harmless**. `better-sqlite3` is an optional dependency — if it cannot compile, npm skips it and the server falls back to Node.js built-in `node:sqlite` (available on Node 22+).
-
-You do **not** need Python, Visual Studio Build Tools, or any C++ compiler to run this project on Node 22+.
-
-If you are on Node 20 or 21 and `better-sqlite3` prebuilds are not available for your platform (there is no `node:sqlite` fallback below Node 22), you have two options:
-
-1. **Upgrade to Node.js 22+** — the built-in `node:sqlite` fallback requires no native compilation at all
-2. **Install build tools** and run `npm rebuild better-sqlite3`:
-   - **Windows:** install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the C++ workload
-   - **macOS:** `xcode-select --install`
-   - **Linux:** `sudo apt install python3 make g++` (Debian/Ubuntu)
-
-### "SQLite backend not available" error on startup
-
-This means neither `better-sqlite3` nor `node:sqlite` could be loaded. The most common cause is running Node.js < 22 without `better-sqlite3` prebuilds. Upgrade to Node.js 22+ to resolve this.
-
-### Database is locked / busy errors
-
-The SQLite database uses WAL mode with a 5-second busy timeout. If you see lock errors:
-
- Ensure only one dashboard server instance is running
- Check for zombie `node server/index.js` processes: `ps aux | grep server/index`
- Delete `data/dashboard.db-wal` and `data/dashboard.db-shm` if the server was killed uncleanly, then restart
-
---
-
-### No sessions appearing after starting Claude Code
-
-**Check 1 — Is the server running?**
-
-```bash
-curl http://localhost:4820/api/health
-# Expected: {"status":"ok","timestamp":"..."}
-```
-
-**Check 2 — Are hooks installed?**
-
-Open `~/.claude/settings.json` and confirm it contains a `hooks` section with entries referencing `hook-handler.js`. If not, run:
-
-```bash
-npm run install-hooks
-```
-
-**Check 3 — Did you start a new Claude Code session after the server started?**
-
-Hooks only apply to sessions started after installation. Restart Claude Code.
-
-**Check 4 — Is Node.js in PATH when Claude Code runs hooks?**
-
-On some systems, the shell environment when Claude Code fires hooks may not include the full PATH. Test with:
-
-```bash
-node --version
-```
-
-If Node.js is not found, use the full path to `node` in the hook command. Edit `scripts/install-hooks.js`, replace `node` with the absolute path (e.g. `/usr/local/bin/node`), and re-run `npm run install-hooks`.
-
---
-
-### Dashboard shows "Disconnected" in the sidebar
-
-The WebSocket connection to the server failed. Ensure the server is running:
-
-```bash
-npm run dev
-```
-
-The client will automatically reconnect every 2 seconds once the server is available.
-
---
-
-### Events Today shows 0 despite recent activity
-
-This was a known timezone bug (fixed in current version). If you are still seeing this, ensure you are running the latest code and restart the server.
-
---
-
-### Port 4820 already in use
-
-```bash
-DASHBOARD_PORT=4821 npm run dev
-```
-
-Then update the Vite proxy in `client/vite.config.ts`:
-
-```ts
-proxy: {
-  "/api": "http://localhost:4821",
-  "/ws":  { target: "ws://localhost:4821", ws: true }
-}
-```
-
-And make sure Claude Code posts hooks to the new port:
-
-```bash
-CLAUDE_DASHBOARD_PORT=4821 claude
-# or edit scripts/hook-handler.js and change the default port
-```
-
---
-
-### Docker / Podman container starts but no sessions appear
-
-**Check 1 — Is the container healthy?**
-
-```bash
-curl http://localhost:4820/api/health
-# Expected: {"status":"ok","timestamp":"..."}
-```
-
-**Check 2 — Did you install hooks on the host?**
-
-Hooks run on the host machine, not inside the container. After the container is up:
-
-```bash
-npm run install-hooks
-```
-
-**Check 3 — Are hooks pointing to the right port?**
-
-Open `~/.claude/settings.json` and verify the hook commands reference `localhost:4820` (or whatever port the container is mapped to). If you changed the port mapping, update hooks accordingly.
-
---
-
-### Docker build fails during `npm ci`
-
-If the build fails in Stage 1 with `better-sqlite3` errors, this is expected and should not block the build — `better-sqlite3` is an optional dependency. If the build still fails:
-
- Ensure you are using the latest Dockerfile (it should use `node:22-alpine` and **not** install `python3`, `make`, or `g++`)
- Run `docker build --no-cache -t agent-monitor .` to force a clean rebuild
- Check that `package.json` has `better-sqlite3` under `optionalDependencies`, not `dependencies`
+This guide has moved into **[INSTALL.md](./INSTALL.md)** — the one install and
+setup guide (it and this file had grown into near-duplicates). Everything that
+was here is there:
+
+| Was in SETUP.md | Now in INSTALL.md |
+|---|---|
+| How it works | [How it works](./INSTALL.md#how-it-works) |
+| Hook auto-installation, environment variables, agent extensions, PWA | [Configuration](./INSTALL.md#configuration) |
+| Database (clear, Settings page, seed) | [Database](./INSTALL.md#database) |
+| Importing existing Claude Code history | [Step 5](./INSTALL.md#step-5--optional-importing-existing-claude-code-history) |
+| Scripts reference, Makefile targets | [Scripts reference](./INSTALL.md#scripts-reference) |
+| Troubleshooting (incl. "Port 4820 already in use") | [Troubleshooting](./INSTALL.md#troubleshooting) |
@@ -1,27 +0,0 @@
---
-name: backend-reviewer
-description: Review backend route and hook logic for regressions, data integrity risks, and missing tests.
-tools: Read, Grep, Glob, Bash
-model: opus
-memory: project
---
-
-You are a backend reviewer for this repository. Review ONLY files under `server/` in the diff you are given — ignore `client/`, `mcp/`, or any other path even if it appears in the same diff range; another reviewer covers those.
-
-Focus on:
- Hook event lifecycle correctness.
- Session/agent state-machine regressions.
- API contract compatibility.
- Transaction and persistence correctness.
- Missing or weak verification coverage.
-
-## Output (MANDATORY — the caller parses your last line)
-
- Findings as `path:line — severity — problem — suggested fix`, most severe first.
- End with exactly one of:
-  - `BACKEND-REVIEW: CLEAN`
-  - `BACKEND-REVIEW: FINDINGS — <n>`
-
-## Agent memory
-
-Record recurring backend defect patterns and false-positive traps you find here (e.g. hook shapes that look wrong but aren't, common state-machine edge cases). Future backend-reviewer runs read this.
@@ -1,27 +0,0 @@
---
-name: frontend-reviewer
-description: Review React UI changes for behavior regressions, state consistency, and UX breakage.
-tools: Read, Grep, Glob, Bash
-model: sonnet
-memory: project
---
-
-You are a frontend reviewer for this repository. Review ONLY files under `client/` in the diff you are given — ignore `server/`, `mcp/`, or any other path even if it appears in the same diff range; another reviewer covers those.
-
-Focus on:
- Routing and navigation consistency.
- State updates from websocket and API responses.
- Loading/empty/error state correctness.
- Breaking visual or interaction regressions.
- Missing tests for changed UI behavior.
-
-## Output (MANDATORY — the caller parses your last line)
-
- Findings as `path:line — severity — problem — suggested fix`, most severe first.
- End with exactly one of:
-  - `FRONTEND-REVIEW: CLEAN`
-  - `FRONTEND-REVIEW: FINDINGS — <n>`
-
-## Agent memory
-
-Record recurring frontend defect patterns and false-positive traps you find here (e.g. websocket race conditions that look wrong but aren't, sibling components that should stay in sync). Future frontend-reviewer runs read this.
@@ -1,74 +0,0 @@
---
-name: "qc-local"
-description: "Local browser-QC agent for the ship-feature-lane pipeline in AgentHub. Launched by the ship-feature-lane skill at Stage 6 (foreground — it gates the pipeline) after e2e, against the lane's OWN feature-branch stack (booted via `agenthub lanes up --qc`; the branch is cut from origin/development, so the stack is development + this feature). Exercises the feature + smoke + reload/re-login coverage via the lane's local-QC Playwright MCP, saves every screenshot to `proof/<feature-slug>/qc-local/` (the AgentHub proof gallery's canonical path), and returns a parseable LOCAL-QC: PASS/FAIL verdict that doubles as the feature user-flow review for the senior gate. <example>Context: ship-feature-lane in a lane finished Stage 3's e2e green. assistant: 'e2e is green — launching the qc-local agent to browser-QC the feature-branch stack and capture the proof gallery.' <commentary>Stage-6 browser QC is the qc-local agent's job; the main session stays off the browser.</commentary></example>"
-model: opus
-color: green
-memory: project
---
-
-You are an elite QA automation engineer validating ONE lane's feature on that lane's OWN local stack (isolated FE/API/DB, nothing shared with other lanes), right after the feature branch's e2e passed (the branch is cut from `origin/development`, so this stack IS development + the feature as of the branch point). You are rigorous, evidence-driven, and autonomous: every claim in your report is backed by a screenshot. You never commit, push, or fix code — you verify, capture proof, and report. Your report IS the feature user-flow review the senior gate reads.
-
-## Context you will be given (by the ship-feature-lane skill)
-
- **The lane's working directory** (your cwd — AgentHub resolves the lane from it automatically; there is no marker file to check).
- **Feature slug** (the `<slug>` of `feat/<slug>`), feature title, and the acceptance points to verify (from the lane spec at `docs/superpowers/specs/lane-<slug>.md` — read it yourself if the summary is thin; `git diff origin/development...HEAD` shows the change surface).
-
-Setup: your cwd is the lane clone. You do NOT write `stage`/`status`/`notes` — the main session owns all state; you have no heartbeat call to make (you run as a synchronous subagent inside the driving session's own turn, so the lane is never seen as stalled while you work).
-
-## Target environment
-
- **App**: the lane's own booted frontend — check `agenthub lanes runtime` (or the `FE_PORT`/equivalent env the skill already resolved) for the actual port; it is isolated per lane. If it's down, don't boot it yourself blindly — return `LOCAL-QC: FAIL — lane stack down (re-run: agenthub lanes up --no-build)`.
- **QC boot env**: the QC stack boots via `agenthub lanes up --qc`, which applies the profile's `QC_BOOT_ENV` (typically mock/stub flags) — LLM/paid-backend features then return CANNED responses. Canned/stub content is EXPECTED there, not a bug; judge the surrounding UX (loading states, rendering, persistence), not the stub text itself.
- **Account / login.** Two paths:
-  - **If a credentials block is embedded at the TOP of this agent** ("⚙ This lane's local-QC credentials"): those ARE your login — type them into the form yourself (`browser_type`, submit) when you hit a login page. You already have them; never read a file/script to fetch them.
-  - **If there is NO embedded block:** the app should already be in a usable/logged-in state (or requires no login for the flows you're testing). If you hit a login page you cannot get past, this profile has no seeded QC account configured yet — return `LOCAL-QC: FAIL — login required, no seed-account mechanism configured for this profile`. Do not guess at credentials or invent a login flow.
- **Tooling**: the **dedicated local-QC Playwright MCP server** (isolated Chromium profile — e.g. `playwright-qa-local` if the profile names it that). You MUST use that server's `mcp__<name>__browser_*` tool family for ALL browser interaction — never the unscoped `mcp__playwright__browser_*` or any other Playwright server (other agents/sessions own those browsers concurrently). If the tools aren't available, return `LOCAL-QC: FAIL — local-QC Playwright MCP not loaded (configure it in .mcp.json and restart the lane session — see the ship-feature-lane skill's Setup section)`.
- **Upload fixtures**: if an **"Upload fixtures dir"** line is injected at the TOP of this agent, use the files in that dir for any data-upload scenario (quote the path; it may contain spaces). If no such line is present, no fixture dataset is configured for this stack — skip data-upload-only scenarios and note that in the report. Put ad-hoc non-fixture files in the lane's `.playwright-mcp/` dir; never source uploads from `/tmp/`.
-
-## Procedure
-
-1. **Load the QC Plan, then execute against it.** The ship-feature-lane skill wrote a `## QC Plan` section into the lane spec (`docs/superpowers/specs/lane-<slug>.md`) at Stage 5 — it is the authoritative scope. Read it first.
-   - **Cover every in-scope scenario** in the plan — skip none.
-   - **Stay in scope** — don't wander into the plan's out-of-scope areas (that over-testing is exactly what the plan exists to prevent); the only unaffected areas you touch are the plan's smoke set.
-   - **If the plan is missing or thin**, derive scenarios yourself from the acceptance points + `git diff origin/development...HEAD` and proceed, covering the same shape: **primary** (each acceptance point, positive AND negative — invalid input, empty state, permission edges), **adjacent** flows sharing routes/components/data, **smoke** (login + main nav + ≥3 unaffected major areas), and **state coverage** (a reload (Cmd+R) on every stateful screen touched, one logout → re-login cycle, back-and-forth navigation between key pages).
-   - **When you discover a real scenario the plan missed** (a genuine risk it didn't anticipate), TEST it AND list it in your report under **"Scenarios discovered during QC"** so the skill folds it into the plan. Do NOT edit the plan file yourself — the skill is its single writer.
-   - **UI/UX & layout rigor — apply to EVERY form/screen the feature touches** (never just a representative one; sibling forms drift):
-     - **Overflow in BOTH axes.** Resize the window NARROWER (width) AND SHORTER (height — e.g. ~560px then ~350px tall), and ALSO grow the content by opening every expandable thing (dropdowns, collapsible sections, "add row" repeaters, multi-select pickers) so a step becomes taller than the viewport. Then confirm: nothing is cut off at the **top** or bottom; any fixed/sticky chrome (page header, wizard **stepper/tabs**, toolbars) stays visible and is NOT clipped; the scroll container actually scrolls; and the primary actions (Save/Next/Submit/Cancel) stay reachable and clickable. A form taller than the page must never hide its header, its step nav, or its buttons.
-     - **Every control has a visible label.** Each input/toggle/select/picker shows a field label. Compare sibling forms — if one labels a control and the other doesn't, that's a defect.
-     - **Visual hierarchy is correct.** Section/group headers are MORE prominent than the field labels inside them (size/weight/color); field labels are consistent across steps and across sibling forms; helper text is least prominent. Flag any inverted or inconsistent hierarchy.
-     - No text truncation/overlap; spacing, alignment, and contrast are reasonable; the form reads as natural, polished UI.
-2. **Execute with the local-QC MCP's tools**:
-   - Use `browser_type` for React controlled inputs — never direct DOM value assignment (it doesn't fire onChange).
-   - After each meaningful action: `browser_snapshot` to verify state, then screenshot (see proof convention).
-   - Don't trust `browser_network_requests` alone for HTTP verification (it double-lists requests); prefer the lane's own backend/service logs if the profile exposes them (`agenthub lanes logs <svc>`).
-   - **Failure triage**: capture a failure screenshot + `browser_snapshot` + `browser_console_messages`, note repro steps, expected vs actual, severity (blocker/major/minor/cosmetic) — then CONTINUE with remaining scenarios unless the app is unusable.
-3. **Proof convention (mandatory — the path is fixed infrastructure, NOT your choice):** EVERY screenshot via `browser_take_screenshot` with `filename: "proof/<feature-slug>/qc-local/<NN>-<what>.png"`, numbered in flow order (e.g. `proof/edit-report/qc-local/03-dialog-open.png`). The MCP server's pinned `--output-dir` lands these in `<lane clone>/.playwright-mcp/proof/...` — the ONLY place the dashboard's gallery reads (`agenthub lanes proof-link` converges a stray `proof/` symlink if needed). Absolute paths, other folders, or invented layouts = the proof is lost.
-
-## Checkpoint & resume  *(rate-limits and crashes must not zero your work)*
-
- **Checkpoint as you go:** after EACH scenario, append one line to `proof/<feature-slug>/qc-local/RESULTS.partial.md` (via the Write/Edit tools on `<lane clone>/.playwright-mcp/proof/...`): `<NN> <scenario> — ✅|❌ — <proof file> — <HEAD sha>`. A mid-run tool error or rate-limit then leaves a resumable trail instead of zeroing the run.
- **Resume on start:** if `RESULTS.partial.md` already exists for this feature AND its HEAD sha matches the tree you're QCing, treat its ✅ scenarios as done (spot-check one) and continue from the first unfinished one. Sha differs → start fresh (delete the stale partial).
- **Bounded stalls:** a single browser step hanging >2 min → close the browser, reload, retry that step ONCE; still stuck → record ❌ with proof and move on. If the run approaches ~45 min, finish the current scenario, mark the rest ⚠️ not-run, and return honestly rather than stalling silently.
-
-## Quality bar (verify before returning)
-
- [ ] Every in-scope QC-Plan item was executed (or marked N/A with a reason); any discovered scenarios are listed for fold-back.
- [ ] Every primary scenario has a screenshot of its end state (pass or fail).
- [ ] Reload tested on every stateful screen touched; one full logout → re-login cycle done.
- [ ] Smoke covered login, navigation, and ≥3 unaffected areas.
- [ ] UI/UX pass done on EACH touched form: tested at narrow AND short viewports AND with dropdowns/expandables open (content taller than the page) — fixed header/stepper/buttons never cut off, scroll works, actions reachable; every control labeled; section headers more prominent than field labels; consistent label styling; no overlap/truncation; natural polished layout.
- [ ] All screenshots under `proof/<feature-slug>/qc-local/` (check with `ls .playwright-mcp/proof/<feature-slug>/qc-local/`).
- [ ] No commits made; password never echoed anywhere.
-
-## Output format (MANDATORY — the skill parses your last line)
-
-A scannable report (this doubles as the user-flow review for the senior gate): a **QC-Plan coverage** view (each in-scope plan item → ✅/❌/⚠️), a **Scenarios discovered during QC** list (anything you tested that wasn't in the plan, for the skill to fold back), issues with severity + repro + which proof file shows each, proof filename list, reload/re-login coverage note, UX observations worth fixing. Then end with exactly one of:
-
- `LOCAL-QC: PASS`
- `LOCAL-QC: FAIL — <comma-separated reasons>`
-
-A FAIL must be specific enough for the lane's fix-loop to act on (page/flow + what broke + proof file).
-
-## Agent memory
-
-Record local-stack QA knowledge as you find it: flaky selectors/flows, features that break after reload or re-login, stub-mode quirks (what canned responses look like per feature), data-setup prerequisites, upload-fixture behaviors, noise-vs-real console errors. Future qc-local runs (any lane) read this.
@@ -1,52 +0,0 @@
---
-name: "senior-gate-reviewer"
-description: "Final GO/NO-GO publish-readiness gate for the ship-feature-lane pipeline in AgentHub. Invoke AFTER the code-review and feature-user-flow-review (qc-local) and AFTER local CI gates + e2e + QC have passed, immediately BEFORE the feature branch is pushed and its PR is opened (base `development`). Returns a single GO or NO-GO verdict with a required-fix list. A GO is the sole authorization to publish the PR. <example>Context: ship-feature-lane in a lane has finished implementation, gates, and reviews and is about to publish the PR. assistant: 'I'll launch the senior-gate-reviewer agent to make the final go/no-go decision before pushing the branch and opening the PR.' <commentary>This is the publish gate — it decides whether the feature is allowed in front of reviewers.</commentary></example>"
-model: opus
-color: red
-memory: project
---
-
-You are the **Senior Gate Reviewer** — the final, independent publish-readiness authority for the ship-feature-lane pipeline. Nothing is pushed or PR'd without your **GO**; the PR a human later merges into `development` is exactly what you approved. You are deliberately skeptical: when in doubt, you return **NO-GO** with a precise, actionable fix list. You do NOT make fixes yourself — you judge, decide, and report.
-
-## Context you will be given (by the ship-feature-lane skill)
-
- **The lane's working directory** (your cwd — AgentHub resolves the lane from it automatically).
- **The original requirement** and the **upfront Q&A answers** (acceptance criteria).
- The **feature branch name** (cut from `origin/development` — the PR base it will target).
- A summary of the **two prior reviews** (code-review + the qc-local user-flow review) and which findings were resolved.
- The **`agenthub lanes sync-base --check` preflight output** (migration-collision check + how far `origin/development` moved since the branch's merge-base).
- Confirmation that **local CI gates** (the profile's lint / test / contract checks), **e2e**, and **browser QC** already passed.
-
-If any of this context is missing, gather it yourself (read the lane spec file the skill wrote, run `git -C <lane> log/diff`).
-
-## Your checks
-
-**Review the PR the reviewers will see.** The PR is `<feature-branch>` based on `origin/development` — judge the change against **the PR diff**: `git -C <lane> diff origin/development...<feature-branch>` (`<feature-branch>` is in your context). There is NO local integration tree in this flow — the branch itself is what ships, and the first combined validation after a human merges it is dev CI + dev-QC; your merge-safety check (#3) is what stands between this branch and that merge. Run checks with `git -C <lane> ...`, `Read`, `Grep`, `make` as needed.
-
-1. **Acceptance** — Does the implementation actually satisfy the original requirement + every upfront Q&A answer? Inspect **the PR diff** (defined above) and, where feasible, confirm the acceptance criteria are met in code. Missing/partial requirement coverage ⇒ NO-GO.
-
-2. **Findings resolved** — Were the PR-code-review and user-flow-review findings actually addressed (not just acknowledged)? Spot-check **the PR diff** for each claimed fix. Unresolved material findings ⇒ NO-GO.
-
-3. **Merge-safety** — Independently verify the branch is safe for a human to merge into `development`. **General principle (any stack):** "the branch is green standalone" is NOT proof the MERGE will be — check for collisions that DON'T surface as git conflicts — duplicate migration identifiers, duplicate fixture/test IDs, API/schema-contract drift, lockfile divergence — in whatever form this stack expresses them, comparing the branch against the CURRENT `origin/development`. Re-run the deterministic preflight yourself if the provided output is stale: `git -C <lane> fetch origin && agenthub lanes sync-base --check <feature-branch>` (exit 5 = collision ⇒ NO-GO with the printed rename; also read its `DEV_DELTA`/`DEV_OVERLAP` — a large overlapping upstream delta means the locally-QC'd behavior may not match post-merge dev, weigh it).
-   - **Stack-specific checks (from the active profile):** read `<lane>/.agenthub/profile/review-checks.md` with the Read tool if it exists, and apply every check it lists (e.g. migration-identifier collisions, API/contract regeneration). Missing or empty → derive the equivalents yourself from the general principle by inspecting the branch vs `origin/development`.
-   - **Obvious regressions / scope creep**: scan **the PR diff** for debug code, secrets, commented-out blocks, unrelated churn, `console.log`/`print` debugging, TODO/FIXME left in critical paths.
-
-4. **UI/UX diligence (when the feature touches any form/screen)** — don't rubber-stamp the QC report; confirm it actually exercised layout rigor, because these defects slip through happy-path QC:
-   - **Overflow** was tested at narrow AND **short** viewports, AND with dropdowns/collapsibles/repeaters **open** so content exceeds the viewport — and no fixed chrome (page header, wizard **stepper/tabs**, action bar) is cut off (especially at the **top**), scroll works, and primary actions stay reachable. A report that only shows one viewport / the happy path has NOT verified this.
-   - Every control is **labeled**, and **section headers are more prominent than field labels** (no inverted hierarchy); labels are consistent across **sibling forms** (if the feature changed two similar forms, they must match).
-   - Spot-check **the PR diff** yourself for UI/UX regressions in these classes (a scroll container that lost `min-h-0`, a removed/altered label, a muted section header, a form-wide container that scrolls the whole page instead of an inner region).
-   If the feature is UI-heavy and the QC didn't demonstrably check the above ⇒ NO-GO with a specific "re-QC: verify <X> at short viewport / with <dropdown> open" instruction.
-
-5. **QC-plan coverage** — read the `## QC Plan` section of the lane spec and the qc-local report (the user-flow review; on a follow-up fix run, also the parent's dev-QC findings the follow-up exists to fix). Confirm every **in-scope** plan item has a result (pass/fail, with proof) — any uncovered in-scope item ⇒ NO-GO ("re-QC: cover <item>"). If a QC report spent effort on the plan's **out-of-scope** areas while leaving in-scope items thin, flag it. Scenarios the agents discovered mid-run should appear folded into the plan.
-
-## Output format (MANDATORY — the skill parses your last line)
-
-Write a short report (acceptance ✓/✗, findings ✓/✗, merge-safety ✓/✗ with one line each), then end with **exactly one** of these as the FINAL line:
-
- `VERDICT: GO`
- `VERDICT: NO-GO — <comma-separated required fixes>`
-
-Rules:
- Only return `GO` when all three checks pass with high confidence.
- A NO-GO fix list must be specific and actionable (file/area + what to do), so the skill's fix-loop can act and re-submit.
- Never push, merge, commit, or modify files. You are read-only. Your verdict is the deliverable.
@@ -19,8 +19,6 @@ Enterprise-grade React + TypeScript dashboard for real-time Claude Code agent mo
 ![PostCSS](https://img.shields.io/badge/PostCSS-8.5-DD3A0A?style=flat-square&logo=postcss&logoColor=white)
 ![Autoprefixer](https://img.shields.io/badge/Autoprefixer-10.4-DD3735?style=flat-square&logo=autoprefixer&logoColor=white)
 ![ESLint](https://img.shields.io/badge/ESLint-8.44-4B32C3?style=flat-square&logo=eslint&logoColor=white)
-![Docker](https://img.shields.io/badge/Docker-20.10-2496ED?style=flat-square&logo=docker&logoColor=white)
-![Podman](https://img.shields.io/badge/Podman-4.0-CC342D?style=flat-square&logo=podman&logoColor=white)
 ![Prometheus](https://img.shields.io/badge/Prometheus-2.x-E6522C?style=flat-square&logo=prometheus&logoColor=white)
 ![Grafana](https://img.shields.io/badge/Grafana-10.x-F46800?style=flat-square&logo=grafana&logoColor=white)
 ![Vitest](https://img.shields.io/badge/Vitest-1.0-646CFF?style=flat-square&logo=vitest&logoColor=white)
@@ -54,7 +52,18 @@ The client is a single-page application (SPA) built with modern web technologies
 - **React 18.3** - Component-based UI with hooks and concurrent features
 - **TypeScript 5.7** - Full type safety across components, utilities, and API contracts
 - **Vite 6.1** - Lightning-fast HMR during development, optimized production builds
- **Tailwind CSS 3.4** - Utility-first CSS framework; colors are CSS-variable-backed tokens (`darkMode: "class"`) so a Dark/Light toggle (next to the language switcher in the sidebar, `useTheme` hook) re-themes the whole app by flipping one class
+- **Tailwind CSS 3.4** - Utility-first CSS framework; colors are CSS-variable-backed tokens (`darkMode: "class"`) so a Dark/Light/System switch (Settings → Appearance; `useTheme` hook — the sidebar has no theme or language controls, the language lives in Settings → Appearance) re-themes the whole app by flipping one class. A **named theme** per mode is one more attribute: `data-theme` on `<html>` (absent for `default`) selects a CSS-variable block in `index.css` — `.dark[data-theme="darcula|apple-dark|orca-dark"]` and `[data-mode="light"][data-theme="apple-light|intellij-light|canvas|orca-light"]` — that overrides only the tokens it changes. `--tint-base` is `var(--surface-3)` and light `--syn-plain` is `var(--fg-primary)`, so a theme never restates them. A new theme is a block there plus an id in `THEMES` (`hooks/useTheme.ts`) and a label in `components/settings/AppearanceSettings.tsx`; its Settings preview needs no hex, because the swatch re-scopes the same variables on its own element. Storage: `theme` = `dark|light|system`, `agenthub.theme.dark` / `agenthub.theme.light` = theme ids (unknown ⇒ `default`); state is read through `useSyncExternalStore`, never cached in the module, so every consumer and every tab agree. An inline `<script>` at the top of `client/index.html` applies the same keys before first paint (no flash of the stock dark palette); it does not validate ids — the hook does, on mount. The workspace terminal's font is the same kind of preference: `agenthub.terminal.font` = `jetbrains|maple|system` (`lib/terminalFont.ts`, default `jetbrains`) and `agenthub.terminal.fontSize` = 11|12|13|14|15|16|18|20 px (`lib/fontSize.ts`, default 13), picked in Settings → Appearance; a change fires `agenthub-font-size` on `window`, so an open terminal re-fits at once. Settings → Appearance → **Text size** (`#text-size`) sets `agenthub.ui.fontSize` = 14|16|17|18 (Small/Default/Large/Larger), the ROOT font size in px (`lib/fontSize.ts`; the index.html script applies it before first paint too); Tailwind's sizes are rem and `index.css` re-states every `text-[Npx]` class in rem, so all text scales with it. All of these keys are synced to the account like the theme (`PREF_KEYS` in `lib/userPrefs.ts` and `server/routes/me.js`)
+
+  **The surface ramp means elevation, and it runs the same direction in both themes: a higher index is LIGHTER in dark and LIGHTER in light.** So in light mode the page is the *darkest* step (`surface-0`, `#eceef2`) and a `.card` is brighter than the page it sits on (`surface-3`, `#fdfdfe`), which is also what makes every `hover:bg-surface-N` lift rather than dim. Light mode originally used Radix slate in its native direction — index up meant darker — which inverted the whole language: a near-white page (the glare complaint) under grey cards that read as recessed. Never "fix" a light-mode colour by swapping which step a component uses; fix the value of the step.
+
+  Other rules that fall out of this:
+  - **The light Default is IntelliJ Light's palette** (`#eceef2` → `#ffffff` neutrals, blue accent, IntelliJ's editor syntax colours); the separate IntelliJ Light theme was folded into it.
+  - Light `--accent` is **not** the dark one: dark's `#0090ff` is 3.3:1 on white. Light mode uses IntelliJ's `#285ac0`, dark enough to clear 4.5:1 as text and under white.
+  - **White text sits on `accent-solid`, never on `accent`.** `--accent` is a TEXT colour; in the dark themes it is the light step (Default `#70b8ff`, Orca Dark `#6aa0f8`) that reads on a near-black card and is far too light to carry white. Every theme also defines `--accent-solid`/`--accent-solid-hover` (Tailwind `bg-accent-solid`) for the fill behind white text — `.btn-primary`, a Switch's on state, a Checkbox tick — darkened until white clears 4.5:1 (Default `#0076d1`). In the light themes the text accent is already dark enough, so `--accent-solid` is simply `var(--accent)`.
+  - `--fg-muted` carries real content (timestamps, counts), so it is held at ≥4.5:1 (`#686359`, 5.4:1 on a card), not at the decorative value the Radix step suggests.
+  - Code colouring goes through the `syntax.*` tokens (`--syn-*`), never fixed Tailwind steps: the dark set is pastel (300-level), the light set is the same hues four steps darker, because a pastel keyword on a light code block is unreadable.
+  - Anything that assumes a dark background — a hardcoded near-black panel, `hover:text-white`, `filter: invert(1)` on a form control glyph — is a light-mode bug. Use tokens, or scope the rule under `.dark`.
+  - **A status/accent FILL is pre-mixed, never translucent.** `bg-status-success/10` and `border-status-danger/40` compile to `color-mix(… , rgb(var(--tint-base)))`, not to `rgb(… / 0.1)` — see `tint()` in `tailwind.config.js`. A translucent tint composites with whatever is behind it, so one "success" chip rendered as five different colours over the five surface steps and washed out on light cards. `--tint-base` is the theme's card surface, so the chip reads the same on the page, in a card, in a modal and inside an input row. This is scoped to `backgroundColor`/`borderColor`: `text-status-warning/80` and `ring-accent/40` stay genuinely translucent (they sit *on* a fill), and the `surface` family keeps its alpha or every scrim would turn solid. Light `--status-*` is two steps darker than Radix 11 so a label clears 4.5:1 against its own densest chip (a 20% tint of itself), not just against the card.
 - **React Router 6.28** - Client-side routing with nested layouts
 - **WebSocket** - Real-time event streaming from server
 - **Lucide Icons** - Modern, consistent icon set
@@ -67,11 +76,10 @@ graph TB
            Layout[Layout Component]
            
            subgraph "Pages"
-                Home[Dashboard<br/>Monitor / Analytics / Health tabs]
+                Home[Dashboard<br/>Monitor / Analytics (incl. Workflow) / Health tabs]
                Sessions[Sessions]
                Detail[SessionDetail]
                Feed[ActivityFeed]
-                Workflows[Workflows]
                Settings[Settings]
            end
            
@@ -98,7 +106,7 @@ graph TB
    end
    
    Router --> Layout
-    Layout --> Home & Sessions & Detail & Feed & Workflows & Settings
+    Layout --> Home & Sessions & Detail & Feed & Settings
    Home & Detail --> AgentCard & StatCard & StatusBadge
    Feed --> EventDetail
    API --> REST
@@ -176,17 +184,36 @@ client/
 │   │   ├── EventDetail.tsx  # Inline hook payload viewer (used by ActivityFeed + SessionDetail)
 │   │   ├── EmptyState.tsx
 │   │   ├── Sidebar.tsx
+│   │   ├── WorkspaceTree.tsx  # Sidebar Workspaces list: one row per workspace, expanding to its sessions (live → its pane, else the transcript), tool filter, search over workspace + session names, row menu
+│   │   ├── lanes/WorkspaceHome.tsx  # /workspace?lane=<id>: repo facts, prompt box (new session in a free pane slot), Recents with cost, Instructions / Memory / Context / Folder
+│   │   ├── lanes/SessionResumeButton.tsx  # The transcript page's explicit Resume (own-folder Claude sessions; warns, then a free pane) / Open pane
+│   │   ├── StatusBar.tsx    # Fixed bottom bar: Live/Disconnected, version, running / needs-you counts, today's cost
 │   │   ├── Layout.tsx
 │   │   ├── RemoteSources.tsx  # Remote Data Sources settings panel (SSH multi-machine collection)
-│   │   └── workflows/      # Workflows page panels: own-pipeline stats + D3 analytics (11 files)
+│   │   ├── SessionToolBadge.tsx  # The CLI that produced a non-Claude session, by its AI Tools label (nothing for Claude)
+│   │   ├── settings/       # Settings panels, among them:
+│   │   │   ├── SettingsRow.tsx              # Row primitives: SettingsSection, SettingsRow, SettingsSwitchRow, SettingsSegmented
+│   │   │   ├── AiToolsSettings.tsx          # Settings → Agents → AI tools: installed/available CLIs, enable/default, install/update
+│   │   │   ├── WorktreeVisibilitySettings.tsx # Settings → Git → Worktrees: which untracked worktrees the sidebar lists
+│   │   │   ├── PricingSettings.tsx          # Model Pricing table, `vendor` filter + Show all models
+│   │   │   ├── ClaudeAgentHubSettings.tsx   # Claude Code → Overview: CLAUDE_HOME, hook status, pricing
+│   │   │   ├── HomeDirSetting.tsx           # CLAUDE_HOME / CODEX_HOME editor (env-owned warning)
+│   │   │   ├── CodexHooksSettings.tsx       # Codex → Overview → Codex hooks card
+│   │   │   ├── ReportSettings.tsx           # Settings → Snapshots & reports: scheduled report definitions, Run now, run history + downloads
+│   │   │   └── AntigravityHooksSettings.tsx # Antigravity → Antigravity hooks card
+│   │   └── workflows/      # Dashboard → Analytics → Workflow panels: own-pipeline stats + D3 analytics (11 files)
 │   │
 │   ├── pages/              # Route pages
-│   │   ├── Dashboard.tsx      # Monitor / Analytics / Health tabs
+│   │   ├── Dashboard.tsx      # Monitor / Analytics / Health tabs; Analytics' date range (Today/This week from Monday/This month from the 1st/7d/30d/90d/All/Custom, `?range=`, lib/dateRange.ts) narrows its headline, cost and token cards
+│   │   ├── History.tsx        # /sessions tab shell (?view=): Sessions · Events (ActivityFeed) · Agents (AgentsTable)
+│   │   ├── AgentsTable.tsx    # /sessions?view=agents (the old /query redirects here): filter agents, sort, page, export CSV/JSON (GET /api/query?entity=agents)
 │   │   ├── Sessions.tsx       # Filterable table; shows each session's real name (synced live from the transcript), falls back to the short ID
-│   │   ├── SessionDetail.tsx  # Agent tree + event timeline + Conversation tab (slash-command pills & output, inline rename markers)
+│   │   ├── SessionDetail.tsx  # Agent tree + event timeline + Conversation tab (slash-command pills & output, inline rename markers) + Replay tab (EventReplay) + Snapshot action
+│   │   ├── SnapshotView.tsx   # Read-only /snapshot/:token page over a frozen session payload
 │   │   ├── ActivityFeed.tsx  # Real-time event log; row click expands payload; Session btn navigates
-│   │   ├── Workflows.tsx
+│   │   ├── Workflows.tsx      # Workflow analytics, rendered in Dashboard → Analytics → Workflow
 │   │   ├── Settings.tsx
+│   │   ├── AiToolConfig.tsx  # Settings → <tool>: the generic tab of every installed, enabled catalog tool (path, Update link, sessions/cost/lanes, default model, vendor pricing, catalog-declared config files; Antigravity adds its hooks card)
 │   │   └── NotFound.tsx
 │   │
 │   ├── lib/                # Core utilities & business logic
@@ -199,10 +226,11 @@ client/
 │   │
 │   ├── hooks/
 │   │   ├── useWebSocket.ts      # Auto-reconnecting WebSocket hook
-│   │   ├── useNotifications.ts  # Browser push notification triggers
-│   │   └── useTheme.ts          # Dark/light mode: toggles the `dark` class, persists to localStorage
+│   │   ├── useLanes.ts          # ONE shared lane list (GET /api/lanes + `lane_update` frames, refetch on reconnect) for the sidebar tree, status bar and Workspace page
+│   │   ├── useNotifications.ts  # Browser push notification triggers; a shown one plays its type's sound (`notifPrefs.sound`/`soundByType`, `playSound` in lib/notify.ts, WAVs in public/sounds/ generated by scripts/gen-notification-sounds.js)
+│   │   └── useTheme.ts          # Dark/light/system mode + per-mode named theme: `dark` class, `data-mode`, `data-theme` on <html>, persisted to localStorage
 │   │
-│   ├── i18n/               # Internationalization (en / zh / vi / ko)
+│   ├── i18n/               # Internationalization (en / vi)
 │   ├── App.tsx             # Root component + router setup
 │   ├── main.tsx            # Entry point
 │   └── index.css           # Tailwind + CSS-variable color tokens (dark/light)
@@ -230,11 +258,12 @@ graph TB
    Sessions[Sessions<br/>filterable table]
    Detail[SessionDetail<br/>agent hierarchy + timeline]
    Feed[ActivityFeed<br/>streaming event log]
-    Workflows[Workflows<br/>Lane pipelines + D3 analytics]
-    Settings[Settings<br/>pricing + notifications + hooks]
+    Workflows[Workflows<br/>Analytics → Workflow sub-tab:<br/>lane pipelines + D3 analytics]
+    Settings[SettingsHub /settings/:section<br/>General: Appearance · Notifications · System<br/>Agents: AI tools, Claude Code, Codex, each catalog tool, AI Proxy<br/>Data: Database · Pricing · Snapshots & reports · Git (credentials, worktree suggestions)]

    App --> Layout
-    Layout --> Dashboard & Sessions & Detail & Feed & Workflows & Settings
+    Layout --> Dashboard & Sessions & Detail & Feed & Settings
+    Dashboard --> Workflows

    Dashboard --> StatCard[StatCard × 6]
    Dashboard --> AgentCard[AgentCard × N]
@@ -277,7 +306,7 @@ sequenceDiagram

 The client uses **local component state** and **React hooks** for state management. No global state library (Redux, Zustand) is used to keep the architecture simple. The one small exception is the **data-scope store** (`lib/dataScope.ts`): a lightweight app-wide store holding the current set of data sources (`local` plus any configured [Remote Data Sources](../server/README.md#remote-data-sources)). Pages read it and append `?sources=` to their API requests, so a single selector narrows the whole app to one or more machines' data. Remote sources are managed from the Settings page via the `RemoteSources` component (`components/RemoteSources.tsx`), which drives the `/api/remote-sources` CRUD/test/sync endpoints and reflects live `remote_source.status` WebSocket updates. When a sync finishes, stats pages refetch via `lib/remoteDataEvents.ts` (`remote_data.updated`, `remote_source.status` with `ok`, or remote `import.progress` complete).

-**Cursor sessions (informational):** Settings surfaces a subtle note on the CLAUDE_HOME, Import History, and Remote Data Sources panels — **Cursor** agent sessions count too because Cursor stores transcripts under the same `~/.claude` paths as Claude Code locally (and on synced remotes).
+**Cursor sessions (informational):** Settings surfaces a subtle note on the CLAUDE_HOME (Settings → Claude Code → Overview), Import History, and Remote Data Sources panels — **Cursor** agent sessions count too because Cursor stores transcripts under the same `~/.claude` paths as Claude Code locally (and on synced remotes).

 ### State Strategy

@@ -394,8 +423,8 @@ Server broadcasts these event types over WebSocket:
 | `notification.received` | Notification object | Notification hook |
 | `remote_source.status` | `{ id, status, error?, last_sync_at? }` (`status`: `idle`/`syncing`/`ok`/`error`/`deleted`) | Remote Data Source sync poller + `/api/remote-sources` routes |
 | `remote_data.updated` | `{ sourceId, source, label?, counters?, last_sync_at? }` | Emitted once per successful remote sync; triggers stats/cost/session refetches. The server also broadcasts `session_created` / `session_updated` (and main-agent frames) for each mirrored session so Kanban/Sessions update immediately |
-| `lane_hook_output` | `{ laneId, hook, stream, line }` | One output line from a lane's profile hook, pushed while it still runs. A build can take minutes; `LaneCard` shows the latest line so a boot does not read as a hang |
-| `lane_runtime` | `{ laneId, runtime? , error? }` | A lane's stack finished coming up or failed to. Carries the fresh runtime facts, so a listener need not re-request them |
+| `lane_hook_output` | `{ laneId, hook, stream, line }` | One output line from a workspace's profile hook, pushed while it still runs. A build can take minutes; `LaneCard` shows the latest line so a boot does not read as a hang |
+| `lane_runtime` | `{ laneId, runtime? , error? }` | A workspace's stack finished coming up or failed to. Carries the fresh runtime facts, so a listener need not re-request them |
 | `lane_hook_result` | `{ laneId, hook, code, error? }` | A profile hook exited (`POST /api/lanes/:id/hook/:name`). `code` is `null` when the hook could not be started |

 ### EventBus Pattern
@@ -447,11 +476,11 @@ graph TB
    Sessions["/sessions (tabs: sessions | events)"]
    Detail["/sessions/:id"]
    Feed["/activity (redirect)"]
-    Workflows["/workflows"]
+    Workflows["/workflows (redirect → /?tab=analytics&sub=workflow)"]
    CcConfig["/cc-config (redirect)"]
    Lanes["/lanes (redirect)"]
    Run["/run (redirect)"]
-    Workspace["/workspace"]
+    Workspace["/workspace?lane=<id> (home) · &run=<runId> (session)"]
    Settings["/settings (tabs: dashboard | claude-code | ...)"]
    NF["/* (NotFound)"]

@@ -476,16 +505,18 @@ function App() {
          <Route index element={<Dashboard />} />
          <Route path="sessions" element={<History />} />
          <Route path="sessions/:id" element={<SessionDetail />} />
+          {/* legacy path - the Query Explorer is now the Agents tab on /sessions */}
+          <Route path="query" element={<Navigate to="/sessions?view=agents" replace />} />
          {/* legacy path - the activity feed is now a tab on /sessions */}
          <Route path="activity" element={<Navigate to="/sessions?view=events" replace />} />
-          <Route path="workflows" element={<Workflows />} />
+          <Route path="workflows" element={<Navigate to="/?tab=analytics&sub=workflow" replace />} />
          {/* legacy path - Claude config now lives in a Settings tab */}
-          <Route path="cc-config" element={<Navigate to="/settings?tool=claude-code" replace />} />
+          <Route path="cc-config" element={<Navigate to="/settings/agents/claude-code" replace />} />
          {/* legacy paths - lanes and runs are one page now */}
          <Route path="lanes" element={<Navigate to="/workspace" replace />} />
          <Route path="run" element={<Navigate to="/workspace" replace />} />
          <Route path="workspace" element={<Workspace />} />
-          <Route path="settings" element={<SettingsHub />} />
+          <Route path="settings/*" element={<SettingsHub />} />
          <Route path="*" element={<NotFound />} />
        </Route>
      </Routes>
@@ -494,6 +525,8 @@ function App() {
 }
 ```

+Every page — `Dashboard`, `History`, `Workspace` (the diff viewer), `SettingsHub`, `SessionDetail`, `SnapshotView` — is a `React.lazy` import in `App.tsx`, each route wrapped in `<Suspense>` (the `Page` helper), so it loads on first visit instead of in the initial bundle; `main.tsx` starts the Workspace chunk early on a `/workspace` deep link. xterm and its addons load with the first terminal (`loadXterm` in `TerminalView.tsx`), the sidebar's add/destructive workspace modals on first open, and Sagi only while it is enabled (`SagiMount`). Only the active UI language is fetched (`i18n/index.ts`, one lazy chunk per language; `main.tsx` renders once it is in). `vite build` writes hidden source maps and a `.br`/`.gz` sibling of every text asset ≥ 1 KB. `App.tsx` also mounts the app-wide `<Toaster />` and `<ConfirmHost />` once, beside `<GlobalTooltip />`.
+
 ### Navigation Flow

 ```mermaid
@@ -603,6 +636,8 @@ graph TB
    style Success fill:#10B981
 ```

+A thrown error carries the server's `error.code` as `code` and the HTTP `status` (plus `runId` from a `409 ESESSIONLIVE` start, `auth` from `409 EGITAUTH`). A `200` that is not JSON — the SPA's `index.html` from a proxy or a dev server that missed the route — throws `code: "EBADRESPONSE"` with the translated `errors:badResponse` message instead of `Unexpected token '<'`. Pages surface a failure through `toast` (`lib/toast.ts`, rendered by `components/Toaster.tsx`; an error toast stays until dismissed) rather than `alert()`, and ask for confirmation through `confirmDialog`/`confirmDiscard` (`lib/confirm.ts`, rendered by `components/ConfirmHost.tsx`) rather than `window.confirm`.
+
 ---

 ## UI Components
@@ -728,6 +763,42 @@ flowchart LR

 Renders the hook payload for a single event inline below its row. Scalars appear as `key: value` pairs; objects and arrays render in a terminal-styled code block with a copy button.

+#### Tooltips (`components/Tooltip.tsx`)
+
+`GlobalTooltip` is mounted once in `App.tsx` and gives **every** control in the
+app the same designed tooltip — there is no wrapper to add at the call site.
+It listens at the document, and on hover (after a 350 ms rest) or on keyboard
+focus (immediately) it takes the element's native `title`, shows it as an
+anchored bubble with an arrow, and puts the attribute back when the bubble
+closes. Consequences worth knowing:
+
+- **Write `title="…"` exactly as before.** That is the whole API. A control
+  keeps its native tooltip, and its accessible name, when JS has not run.
+- **Opt out with `data-tip-off`** where the browser's own tooltip is wanted.
+- The bubble is built from theme tokens (`TOOLTIP_SURFACE`), so it is legible
+  in light mode; it flips above/below, clamps to the viewport, and closes on
+  scroll, resize, pointer-down or `Escape`.
+- `Tip` (`components/Tip.tsx`) stays separate and cursor-following for
+  expanding a truncated **number** inside a line of text, but draws the same
+  surface so the two read as one thing.
+
+#### MarkdownPreview (`components/MarkdownPreview.tsx`)
+
+A `.md`/`.markdown`/`.mdx` file (`isMarkdown`) rendered for reading with
+`react-markdown` + `remark-gfm` (tables, task lists, strikethrough). It sits
+behind a **Preview** / **Raw** toggle in two places: the config explorer's
+`FileViewer` and the Changes panel's whole-file view (`lane-file-preview`,
+reset to Raw on every file switch; the editor still opens from Raw). Raw HTML
+in the file is shown as text, never run (no `rehype-raw`), links open in a new
+tab, and a leading YAML frontmatter block is shown as a code block. Styles are
+the `.md-preview` rules in `index.css`, built from theme tokens.
+
+#### Metric tooltips (`common:insights.help.*`)
+
+The dotted-underline tooltips on jargon metrics (`StatCard`'s and
+`SessionOverview`'s `help` prop) are worded in `common:insights.help.*`, `en` +
+`vi`.
+
 ---

 ## Utilities
@@ -1,18 +1,40 @@
 <!doctype html>
 <html lang="en" class="dark">
  <head>
+    <!-- Apply the saved appearance before first paint (same keys as
+         src/hooks/useTheme.ts, which re-applies and validates on mount, and
+         src/lib/fontSize.ts). -->
+    <script>
+      try {
+        var m = localStorage.getItem("theme");
+        var d =
+          m === "light"
+            ? false
+            : m === "system"
+              ? !(window.matchMedia && !matchMedia("(prefers-color-scheme: dark)").matches)
+              : true;
+        var r = document.documentElement;
+        var t = localStorage.getItem("agenthub.theme." + (d ? "dark" : "light"));
+        r.classList.toggle("dark", d);
+        r.setAttribute("data-mode", d ? "dark" : "light");
+        if (t && t !== "default") r.setAttribute("data-theme", t);
+        // Text size (src/lib/fontSize.ts, UI_FONT_SIZES): the root font size.
+        var f = Number(localStorage.getItem("agenthub.ui.fontSize"));
+        if (f === 14 || f === 17 || f === 18) r.style.fontSize = f + "px";
+      } catch (e) {}
+    </script>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
-    <link rel="apple-touch-icon" href="/favicon.svg" />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <link rel="apple-touch-icon" href="/favicon.ico" />
    <link rel="manifest" href="/manifest.json" />
    <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>AgentHub - 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."
+      content="Run, steer and track your AI coding agents in one browser tab: workspaces with live terminals for Claude Code, Codex and more, built-in Git, chat replay, usage and cost tracking, and alerts - local-first and real-time."
    />
    <meta
      name="keywords"
@@ -23,27 +45,27 @@

    <!-- 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:site_name" content="AgentHub" />
+    <meta property="og:title" content="AgentHub - 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."
+      content="Run, steer and track your AI coding agents in one browser tab: workspaces with live terminals for Claude Code, Codex and more, built-in Git, chat replay, usage and cost tracking, and alerts - local-first and real-time."
    />
-    <meta property="og:image" content="/og-image.svg" />
+    <meta property="og:image" content="/og-image.png" />
    <meta property="og:image:width" content="1200" />
    <meta property="og:image:height" content="630" />
-    <meta property="og:image:type" content="image/svg+xml" />
-    <meta property="og:image:alt" content="Agent Dashboard - real-time Claude Code monitoring" />
+    <meta property="og:image:type" content="image/png" />
+    <meta property="og:image:alt" content="AgentHub - run, steer and track your AI coding agents" />

    <!-- 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="AgentHub - 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."
+      content="Run, steer and track your AI coding agents in one browser tab: workspaces with live terminals for Claude Code, Codex and more, built-in Git, chat replay, usage and cost tracking, and alerts - local-first and real-time."
    />
-    <meta name="twitter:image" content="/og-image.svg" />
-    <meta name="twitter:image:alt" content="Agent Dashboard - real-time Claude Code monitoring" />
+    <meta name="twitter:image" content="/og-image.png" />
+    <meta name="twitter:image:alt" content="AgentHub - run, steer and track your AI coding agents" />
    <meta name="twitter:creator" content="@smartgift" />

    <!-- JSON-LD structured data -->
@@ -51,8 +73,8 @@
      {
        "@context": "https://schema.org",
        "@type": "WebApplication",
-        "name": "Agent Dashboard",
-        "description": "Real-time monitoring platform for Claude Code agent activity. Tracks sessions, agents, tool events, token usage analytics, cost tracking, and browser notifications via native hooks with live WebSocket push.",
+        "name": "AgentHub",
+        "description": "Run, steer and track your AI coding agents in one browser tab: workspaces with live terminals for Claude Code, Codex and more, built-in Git, chat replay, usage and cost tracking, and alerts - local-first and real-time.",
        "applicationCategory": "DeveloperApplication",
        "operatingSystem": "Windows, macOS, Linux",
        "softwareVersion": "1.0.0",
@@ -61,12 +83,12 @@
          "name": "SmartGift",
          "url": "https://smartgift.vn"
        },
-        "codeRepository": "https://git.smartgift.io.vn/Smartgift-AI/Claude-Code-Monitor",
-        "featureList": "Real-time dashboard, Kanban board, Session tracking, Activity feed, Token usage analytics, Cost tracking, Browser notifications, WebSocket live updates, CLI statusline"
+        "codeRepository": "https://git.smartgift.io.vn/Smartgift-AI/AgentHub",
+        "featureList": "Real-time dashboard, Kanban board, Session tracking, Activity feed, Token usage analytics, Cost tracking, Browser notifications, WebSocket live updates"
      }
    </script>
  </head>
-  <body class="bg-surface-0 text-gray-200 antialiased">
+  <body class="bg-surface-0 text-fg-primary antialiased">
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
@@ -11,10 +11,18 @@
    "test:watch": "NODE_OPTIONS=--no-experimental-webstorage vitest"
  },
  "dependencies": {
+    "@codemirror/commands": "^6.11.1",
+    "@codemirror/merge": "^6.12.2",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.13",
    "@fontsource/inter": "^5.2.8",
    "@fontsource/jetbrains-mono": "^5.2.8",
+    "@fontsource/maple-mono": "^5.3.0",
    "@xterm/addon-canvas": "^0.7.0",
+    "@xterm/addon-clipboard": "^0.1.0",
    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/addon-search": "^0.15.0",
+    "@xterm/addon-web-links": "^0.11.0",
    "@xterm/xterm": "^5.5.0",
    "d3": "^7.9.0",
    "i18next": "^26.0.8",
@@ -23,7 +31,9 @@
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "react-i18next": "^17.0.4",
-    "react-router-dom": "^6.28.2"
+    "react-markdown": "^10.1.0",
+    "react-router-dom": "^6.28.2",
+    "remark-gfm": "^4.0.1"
  },
  "devDependencies": {
    "@testing-library/jest-dom": "^6.9.1",
@@ -0,0 +1,3 @@
+<svg width="248" height="248" viewBox="0 0 248 248" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M52.4285 162.873L98.7844 136.879L99.5485 134.602L98.7844 133.334H96.4921L88.7237 132.862L62.2346 132.153L39.3113 131.207L17.0249 130.026L11.4214 128.844L6.2 121.873L6.7094 118.447L11.4214 115.257L18.171 115.847L33.0711 116.911L55.485 118.447L71.6586 119.392L95.728 121.873H99.5485L100.058 120.337L98.7844 119.392L97.7656 118.447L74.5877 102.732L49.4995 86.1905L36.3823 76.62L29.3779 71.7757L25.8121 67.2858L24.2839 57.3608L30.6515 50.2716L39.3113 50.8623L41.4763 51.4531L50.2636 58.1879L68.9842 72.7209L93.4357 90.6804L97.0015 93.6343L98.4374 92.6652L98.6571 91.9801L97.0015 89.2625L83.757 65.2772L69.621 40.8192L63.2534 30.6579L61.5978 24.632C60.9565 22.1032 60.579 20.0111 60.579 17.4246L67.8381 7.49965L71.9133 6.19995L81.7193 7.49965L85.7946 11.0443L91.9074 24.9865L101.714 46.8451L116.996 76.62L121.453 85.4816L123.873 93.6343L124.764 96.1155H126.292V94.6976L127.566 77.9197L129.858 57.3608L132.15 30.8942L132.915 23.4505L136.608 14.4708L143.994 9.62643L149.725 12.344L154.437 19.0788L153.8 23.4505L150.998 41.6463L145.522 70.1215L141.957 89.2625H143.994L146.414 86.7813L156.093 74.0206L172.266 53.698L179.398 45.6635L187.803 36.802L193.152 32.5484H203.34L210.726 43.6549L207.415 55.1159L196.972 68.3492L188.312 79.5739L175.896 96.2095L168.191 109.585L168.882 110.689L170.738 110.53L198.755 104.504L213.91 101.787L231.994 98.7149L240.144 102.496L241.036 106.395L237.852 114.311L218.495 119.037L195.826 123.645L162.07 131.592L161.696 131.893L162.137 132.547L177.36 133.925L183.855 134.279H199.774L229.447 136.524L237.215 141.605L241.8 147.867L241.036 152.711L229.065 158.737L213.019 154.956L175.45 145.977L162.587 142.787H160.805V143.85L171.502 154.366L191.242 172.089L215.82 195.011L217.094 200.682L213.91 205.172L210.599 204.699L188.949 188.394L180.544 181.069L161.696 165.118H160.422V166.772L164.752 173.152L187.803 207.771L188.949 218.405L187.294 221.832L181.308 223.959L174.813 222.777L161.187 203.754L147.305 182.486L136.098 163.345L134.745 164.2L128.075 235.42L125.019 239.082L117.887 241.8L111.902 237.31L108.718 229.984L111.902 215.452L115.722 196.547L118.779 181.541L121.58 162.873L123.291 156.636L123.14 156.219L121.773 156.449L107.699 175.752L86.304 204.699L69.3663 222.777L65.291 224.431L58.2867 220.768L58.9235 214.27L62.8713 208.48L86.304 178.705L100.44 160.155L109.551 149.507L109.462 147.967L108.959 147.924L46.6977 188.512L35.6182 189.93L30.7788 185.44L31.4156 178.115L33.7079 175.752L52.4285 162.873Z" fill="#D97757"/>
+</svg>
@@ -0,0 +1 @@
+<svg version="1.2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 250" width="250" height="250"><defs><linearGradient id="P" gradientUnits="userSpaceOnUse"/><linearGradient id="g1" x2="1" href="#P" gradientTransform="matrix(0,249.335,-249.128,0,125,.332)"><stop stop-color="#b1a7ff"/><stop offset=".5" stop-color="#7a9dff"/><stop offset="1" stop-color="#3941ff"/></linearGradient></defs><style>.a{fill:url(#g1)}</style><path class="a" d="m84.3 5.1q3.7-1.5 7.7-2.6 3.9-1 7.9-1.6 4-0.5 8.1-0.6 4 0 8 0.5 20.7 2.4 37.1 17.7 0.1 0.1 0.4 0.3 0.1 0 0.2 0 0 0 0.2 0 0 0 0.1 0 0 0 0.1 0 5.2-1.4 10.7-1.9 5.4-0.4 10.7 0.1 5.5 0.4 10.7 1.9 5.2 1.3 10.1 3.6l0.6 0.4 1.6 0.8q5.2 2.5 9.7 6.1 4.7 3.4 8.6 7.7 3.8 4.3 6.9 9.2 3 4.8 5.2 10.2 4.3 10.5 4.3 22.1 0.2 2.1 0 4.2-0.1 2.2-0.2 4.3-0.3 2.1-0.7 4.3-0.4 2.1-0.9 4.1 0 0.2 0 0.4 0 0.2 0 0.5 0 0.1 0.1 0.4 0.1 0.1 0.3 0.3 12.3 12.6 16.3 30 6 29.7-12.2 53.5l-1.9 2.2q-3 3.5-6.5 6.4-3.4 3.1-7.3 5.5-3.8 2.4-8.1 4.2-4.1 1.9-8.5 3.2-0.3 0-0.4 0.2-0.3 0-0.4 0.1-0.1 0.1-0.3 0.4 0 0.1-0.1 0.3c-2.7 7.7-5.3 14.2-10.2 20.7-12.5 16.5-30.8 25.5-51.5 25.5q-24.6-0.1-43.6-18.1-0.2-0.1-0.4-0.2-0.2-0.1-0.4-0.1-0.2 0-0.3 0-0.3 0-0.4 0c-5.4 1.7-10.9 1.9-16.7 1.9q-3.5 0-7-0.5-3.4-0.4-6.9-1.2-3.3-0.8-6.6-2-3.3-1.2-6.4-2.8-3.3-1.6-6.4-3.6-3-2-5.8-4.3-3-2.3-5.5-5-2.5-2.6-4.6-5.6c-2.2-2.7-4.3-5.4-5.8-8.5q-0.8-1.6-1.6-3.2-0.6-1.7-1.3-3.3-0.7-1.7-1.2-3.4-0.5-1.6-1-3.4-1.1-4-1.6-7.9-0.6-4-0.6-8 0-4 0.6-8 0.4-4 1.4-8 0 0 0-0.1 0-0.1 0-0.1 0.2-0.2 0.2-0.3 0-0.1-0.2-0.1 0-0.2 0-0.3 0-0.1-0.1-0.1 0-0.2 0-0.2-0.1-0.1-0.1-0.1-2.4-2.5-4.6-5.2-2.1-2.7-4-5.4-1.7-3-3.2-6-1.5-3.1-2.6-6.3-0.8-2-1.3-4.1-0.7-2-1.1-4-0.4-2.1-0.7-4.2-0.2-2.2-0.4-4.3-0.2-2.8-0.1-5.6 0-2.8 0.3-5.4 0.1-2.8 0.6-5.6 0.4-2.8 1.1-5.5 7-23.1 26.9-36.3 4.3-2.9 8.2-4.5 4.5-1.9 9-3.2 0.2 0 0.3-0.1 0.1-0.2 0.3-0.3 0.1 0 0.1-0.3 0.1-0.1 0.1-0.2 1-3.1 2.2-6 1-2.9 2.5-5.7 1.5-3 3.2-5.6 1.7-2.7 3.7-5.1 2.5-3.2 5.3-5.9 3-2.8 6.1-5.4 3.2-2.4 6.8-4.4 3.5-2 7.2-3.5zm48.3 146.4c-2.3 0.1-4.4 1-6 2.8-1.5 1.6-2.4 3.7-2.4 5.9 0 2.3 0.9 4.4 2.4 6.2 1.6 1.6 3.7 2.5 6 2.6h50.4c2.4 0.1 4.8-0.6 6.5-2.4 1.7-1.6 2.8-4 2.8-6.4 0-2.4-1.1-4.7-2.8-6.3-1.7-1.8-4.1-2.6-6.5-2.4zm-56.7-64.9c-1.2-1.9-3-3.4-5.3-3.9-2.2-0.5-4.5-0.3-6.5 0.9-2 1.1-3.5 3-4.1 5.2-0.7 2.2-0.4 4.6 0.6 6.5l17.7 30.9-17.5 29.5c-1.2 2-1.6 4.5-1.1 6.8 0.7 2.3 2.1 4.1 4.1 5.3 2 1.2 4.4 1.6 6.7 0.9 2.2-0.5 4.2-1.9 5.4-3.9l20.1-34.1q0.7-0.9 0.9-2.1 0.3-1.1 0.3-2.3 0-1.2-0.3-2.2-0.2-1.2-0.8-2.2z"/></svg>
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 250 250" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g transform="matrix(10.416667,0,0,10.416667,0,0)">
+        <path d="M0,4.391C-0,1.982 1.982,0 4.391,0C4.391,0 19.609,-0 19.609,-0C22.018,-0 24,1.982 24,4.391C24,4.391 24,19.609 24,19.609C24,22.018 22.018,24 19.609,24C19.609,24 4.391,24 4.391,24C1.982,24 -0,22.018 -0,19.609C-0,19.609 0,4.391 0,4.391Z" style="fill:url(#_Linear1);fill-rule:nonzero;"/>
+    </g>
+    <g transform="matrix(10.416667,0,0,10.416667,0,0)">
+        <path d="M19.74,1.444C21.285,1.444 22.556,2.715 22.556,4.26L22.556,19.74C22.556,21.285 21.285,22.556 19.74,22.556L4.26,22.556C2.715,22.556 1.444,21.285 1.444,19.74L1.444,4.26C1.444,2.715 2.715,1.444 4.26,1.444L19.74,1.444ZM7.236,8.564L14.988,12.292L7.236,16.019L7.236,18.821L16.793,14.225L16.793,10.359L7.236,5.763L7.236,8.564Z" style="fill:rgb(30,30,46);"/>
+    </g>
+    <defs>
+        <linearGradient id="_Linear1" x1="0" y1="0" x2="1" y2="0" gradientUnits="userSpaceOnUse" gradientTransform="matrix(-24,9.907,-9.907,-24,24,6.587)"><stop offset="0" style="stop-color:rgb(238,77,93);stop-opacity:1"/><stop offset="0.33" style="stop-color:rgb(179,129,221);stop-opacity:1"/><stop offset="0.48" style="stop-color:rgb(32,124,254);stop-opacity:1"/><stop offset="1" style="stop-color:rgb(32,124,254);stop-opacity:1"/></linearGradient>
+    </defs>
+</svg>
@@ -0,0 +1 @@
+<svg version="1.2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 250" width="250" height="250"><defs><linearGradient id="P" gradientUnits="userSpaceOnUse"/><linearGradient id="g1" x2="1" href="#P" gradientTransform="matrix(288.354,233.302,-248.835,307.552,-6.865,4.771)"><stop stop-color="#ff4d4d"/><stop offset="1" stop-color="#991b1b"/></linearGradient><linearGradient id="g2" x2="1" href="#P" gradientTransform="matrix(44.906,54.969,-62.556,51.105,0,100.75)"><stop stop-color="#ff4d4d"/><stop offset="1" stop-color="#991b1b"/></linearGradient><linearGradient id="g3" x2="1" href="#P" gradientTransform="matrix(52.229,46.969,-41.209,45.824,201.927,103.677)"><stop stop-color="#ff4d4d"/><stop offset="1" stop-color="#991b1b"/></linearGradient></defs><style>.a{fill:url(#g1)}.b{fill:url(#g2)}.c{fill:url(#g3)}.d{fill:#ff4d4d}.e{fill:#050810}.f{fill:#00e5cc}</style><path class="a" d="m125 26.8c-65.9-0.1-98.9 54.9-98.9 98.9 0 43.9 33 87.9 65.9 98.9v21.9h22v-21.9c0 0 11 4.3 22 0v21.9h22v-21.9c32.9-11 65.9-55 65.9-98.9 0-44-33-99-98.9-99z"/><path class="b" d="m37.1 103.7c-33-11-44 11-33 32.9 11 22 33 11 44-10.9 6.6-15.4 0-22-11-22z"/><path class="c" d="m212.9 103.7c33-11 44 11 33 32.9-11 22-33 11-44-10.9-6.6-15.4 0-22 11-22z"/><path class="d" d="m57.4 19.5c4.9-2.9 10.8-2.4 16.8 0.4 6 2.8 12.7 8.1 20.2 15.5 0.6 0.6 0.9 1.5 0.9 2.3 0 0.9-0.3 1.8-0.9 2.4-0.7 0.6-1.5 0.9-2.4 0.9-0.8 0-1.7-0.3-2.3-0.9-7.2-7.2-13.3-11.9-18.3-14.2-4.9-2.3-8.3-2.1-10.6-0.7-0.8 0.4-1.6 0.4-2.4 0.2-0.9-0.2-1.5-0.7-2-1.5-0.4-0.7-0.5-1.5-0.4-2.3 0.2-0.9 0.7-1.6 1.4-2.1zm118.4 0.4c6-2.8 11.9-3.3 16.8-0.4 0.7 0.5 1.2 1.2 1.4 2.1 0.1 0.8 0 1.6-0.4 2.3-0.5 0.8-1.1 1.3-2 1.5-0.8 0.2-1.6 0.2-2.4-0.2-2.3-1.4-5.7-1.6-10.6 0.7-5 2.3-11.1 7-18.3 14.2-0.6 0.6-1.5 0.9-2.3 0.9-0.9 0-1.7-0.3-2.4-0.9-0.6-0.6-0.9-1.5-0.9-2.4 0-0.8 0.3-1.7 0.9-2.3 7.5-7.4 14.2-12.7 20.2-15.5z"/><path class="e" d="m92 94.9c3.5 0 6.9-1.4 9.4-3.9 2.4-2.5 3.8-5.8 3.8-9.3 0-3.5-1.4-6.9-3.8-9.3-2.5-2.5-5.9-3.9-9.4-3.9-3.5 0-6.8 1.4-9.3 3.9-2.5 2.4-3.9 5.8-3.9 9.3 0 3.5 1.4 6.8 3.9 9.3 2.5 2.5 5.8 3.9 9.3 3.9zm66 0c3.5 0 6.8-1.4 9.3-3.9 2.5-2.5 3.9-5.8 3.9-9.3 0-3.5-1.4-6.9-3.9-9.3-2.5-2.5-5.8-3.9-9.3-3.9-3.5 0-6.9 1.4-9.4 3.9-2.4 2.4-3.8 5.8-3.8 9.3 0 3.5 1.4 6.8 3.8 9.3 2.5 2.5 5.9 3.9 9.4 3.9z"/><path class="f" d="m94.2 85c1.5 0 2.9-0.6 3.9-1.6 1-1 1.6-2.4 1.6-3.9 0-1.5-0.6-2.9-1.6-3.9-1-1-2.4-1.6-3.9-1.6-1.4 0-2.8 0.6-3.9 1.6-1 1-1.6 2.4-1.6 3.9 0 1.5 0.6 2.8 1.6 3.9 1.1 1 2.5 1.6 3.9 1.6zm66 0c1.4 0 2.8-0.6 3.8-1.6 1.1-1 1.7-2.4 1.7-3.9 0-1.5-0.6-2.8-1.7-3.9-1-1-2.4-1.6-3.8-1.6-1.5 0-2.9 0.6-3.9 1.6-1 1-1.6 2.4-1.6 3.9 0 1.5 0.6 2.9 1.6 3.9 1 1 2.4 1.6 3.9 1.6z"/></svg>
@@ -13,15 +13,15 @@
  "categories": ["developer-tools", "productivity"],
  "icons": [
    {
-      "src": "/favicon.svg",
-      "sizes": "any",
-      "type": "image/svg+xml",
+      "src": "/favicon.ico",
+      "sizes": "32x32",
+      "type": "image/x-icon",
      "purpose": "any"
    },
    {
-      "src": "/favicon.svg",
-      "sizes": "any",
-      "type": "image/svg+xml",
+      "src": "/favicon.ico",
+      "sizes": "32x32",
+      "type": "image/x-icon",
      "purpose": "maskable"
    }
  ]
@@ -1,12 +1,15 @@
 /**
- * @description Service Worker for caching static assets and handling push notifications.
+ * @description Service Worker: network-first navigations with an offline fallback, and push
+ * notifications. Hashed `/assets/` bundles are left to the HTTP cache (immutable).
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

 // Bump this any time the SW logic changes - old clients will install the new
 // SW, drop their existing caches in `activate`, and `skipWaiting` so the
 // freshly-built bundle starts being served on the very next request.
-const CACHE_NAME = "dashboard-v2";
+// v3: drops v2's cache-first `/assets/` entries, which grew with every build
+// and were never pruned.
+const CACHE_NAME = "dashboard-v3";

 self.addEventListener("install", () => {
  // No pre-cache: network-first below means the cache fills lazily, and
@@ -39,25 +42,10 @@ self.addEventListener("fetch", (event) => {
  )
    return;

-  // Hashed bundles under /assets/ are immutable for a given URL - cache-first
-  // is safe and fast. A new build emits new filenames, so stale entries simply
-  // don't get re-requested.
-  if (url.pathname.startsWith("/assets/")) {
-    event.respondWith(
-      caches.match(request).then(
-        (cached) =>
-          cached ||
-          fetch(request).then((response) => {
-            if (response.ok && response.type === "basic") {
-              const clone = response.clone();
-              caches.open(CACHE_NAME).then((cache) => cache.put(request, clone));
-            }
-            return response;
-          })
-      )
-    );
-    return;
-  }
+  // Hashed bundles under /assets/ are immutable and the server marks them so:
+  // the browser's HTTP cache keeps them. Caching them here too only grew a
+  // second copy of every build, forever.
+  if (url.pathname.startsWith("/assets/")) return;

  // Everything else (navigations, sw.js, manifest, icons, root /): network-first
  // with cache fallback. The user always gets the freshest UI while online and
@@ -87,13 +75,19 @@ self.addEventListener("push", (event) => {

 self.addEventListener("notificationclick", (event) => {
  event.notification.close();
+  const url = event.notification.data?.url;
  event.waitUntil(
    clients.matchAll({ type: "window" }).then((windowClients) => {
      for (const client of windowClients) {
-        if (client.focus) {
+        if ("focus" in client) {
+          // Reuse an already-open tab instead of stacking a new one — that's
+          // also why `navigate` (same-origin only) beats postMessage: it works
+          // even if the page hasn't wired up a listener for this.
+          if (url && "navigate" in client) client.navigate(url).catch(() => {});
          return client.focus();
        }
      }
+      if (url && clients.openWindow) return clients.openWindow(url);
    })
  );
 });
@@ -38,12 +38,11 @@
 * ## Internal dependencies
 * - `./components/Layout`
 * - `./components/SplashScreen`
- * - `./pages/Dashboard`
- * - `./pages/History`
- * - `./pages/SessionDetail`
- * - `./pages/Workflows`
- * - `./pages/SettingsHub`
- * - `./pages/Workspace`
+ * - `./pages/Dashboard` (lazy)
+ * - `./pages/History` (lazy)
+ * - `./pages/SessionDetail` (lazy)
+ * - `./pages/SettingsHub` (lazy)
+ * - `./pages/Workspace` (lazy)
 *
 * ## Testing pointers
 * - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
@@ -55,23 +54,75 @@
 * - `skills/file-headers/` — mandatory `@author` header policy.
 * ============================================================================= */

-import { BrowserRouter, Routes, Route, Navigate } from "react-router-dom";
-import { useCallback } from "react";
+import { BrowserRouter, Routes, Route, Navigate, useParams, useLocation } from "react-router-dom";
+import { lazy, Suspense, useCallback, useEffect, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
 import { Layout } from "./components/Layout";
 import { DocumentTitle } from "./components/DocumentTitle";
 import { SplashScreen } from "./components/SplashScreen";
-import { Dashboard } from "./pages/Dashboard";
-import { History } from "./pages/History";
-import { SessionDetail } from "./pages/SessionDetail";
-import { Workflows } from "./pages/Workflows";
-import { SettingsHub } from "./pages/SettingsHub";
-import { Workspace } from "./pages/Workspace";
+import { GlobalTooltip } from "./components/Tooltip";
+import { Toaster } from "./components/Toaster";
+import { ConfirmHost } from "./components/ConfirmHost";
+import { RouteErrorBoundary, reloadOnce } from "./components/RouteErrorBoundary";
+import { usePermissions } from "./components/AuthGate";
 import { NotFound } from "./pages/NotFound";
 import { useWebSocket } from "./hooks/useWebSocket";
 import { useNotifications } from "./hooks/useNotifications";
 import { eventBus } from "./lib/eventBus";
+import { copyOnCtrlShiftC } from "./lib/keys";
+import { reloadOnNewBuild } from "./lib/newBuildReload";
 import type { WSMessage } from "./lib/types";

+// The heavy pages (xterm, the diff viewer, the settings editors) load on first
+// visit instead of in the initial bundle — the Dashboard and History too, so the
+// entry chunk holds only the shell.
+const Dashboard = lazy(() => import("./pages/Dashboard").then((m) => ({ default: m.Dashboard })));
+const History = lazy(() => import("./pages/History").then((m) => ({ default: m.History })));
+const Workspace = lazy(() => import("./pages/Workspace").then((m) => ({ default: m.Workspace })));
+const SettingsHub = lazy(() =>
+  import("./pages/SettingsHub").then((m) => ({ default: m.SettingsHub }))
+);
+const SessionDetail = lazy(() =>
+  import("./pages/SessionDetail").then((m) => ({ default: m.SessionDetail }))
+);
+const SnapshotView = lazy(() =>
+  import("./pages/SnapshotView").then((m) => ({ default: m.SnapshotView }))
+);
+const FilesPage = lazy(() => import("./pages/FilesPage").then((m) => ({ default: m.FilesPage })));
+const Administration = lazy(() =>
+  import("./pages/Administration").then((m) => ({ default: m.Administration }))
+);
+const Artifacts = lazy(() => import("./pages/Artifacts").then((m) => ({ default: m.Artifacts })));
+
+function PageFallback() {
+  const { t } = useTranslation();
+  return (
+    <div role="status" className="flex items-center justify-center py-20 text-sm text-fg-muted">
+      {t("common:loading")}
+    </div>
+  );
+}
+
+function Page({ children }: { children: ReactNode }) {
+  const { pathname } = useLocation();
+  return (
+    <RouteErrorBoundary resetKey={pathname}>
+      <Suspense fallback={<PageFallback />}>{children}</Suspense>
+    </RouteErrorBoundary>
+  );
+}
+
+/** A page only a shared server needs (the File Explorer): local mode goes home. */
+function ServerOnly({ children }: { children: ReactNode }) {
+  return usePermissions().local ? <Navigate to="/" replace /> : <>{children}</>;
+}
+
+/** Keyed by the id so moving to another session starts from fresh state. */
+function SessionDetailRoute() {
+  const { id } = useParams();
+  return <SessionDetail key={id} />;
+}
+
 /**
 * Application root component mounted by {@link main.tsx}.
 * @returns Routed dashboard UI inside `BrowserRouter`.
@@ -84,26 +135,127 @@ export default function App() {
  const { connected } = useWebSocket(onMessage);
  useNotifications();

+  // A self-update replaced the hashed assets this tab still references: Vite
+  // reports the failed preload here; reload once (guarded against loops).
+  useEffect(() => {
+    const onPreloadError = (e: Event) => {
+      if (reloadOnce()) e.preventDefault();
+    };
+    window.addEventListener("vite:preloadError", onPreloadError);
+    return () => window.removeEventListener("vite:preloadError", onPreloadError);
+  }, []);
+
+  // The server came back as a newer version (any tab, any way it was updated):
+  // load its UI build instead of leaving the user to press F5.
+  useEffect(() => reloadOnNewBuild(), []);
+
+  // Ctrl+Shift+C is copy here (Linux terminal habit), not the browser's inspector.
+  useEffect(() => {
+    window.addEventListener("keydown", copyOnCtrlShiftC, true);
+    return () => window.removeEventListener("keydown", copyOnCtrlShiftC, true);
+  }, []);
+
  return (
    <>
      <SplashScreen />
+      {/* One renderer gives every `title` in the app the designed bubble —
+          see components/Tooltip.tsx for why it is not a wrapper component. */}
+      <GlobalTooltip />
+      {/* App-wide toasts and promise-based confirms: lib/toast.ts, lib/confirm.ts. */}
+      <Toaster />
+      <ConfirmHost />
      <BrowserRouter>
        <DocumentTitle />
        <Routes>
          <Route element={<Layout wsConnected={connected} />}>
-            <Route index element={<Dashboard />} />
-            <Route path="sessions" element={<History />} />
-            <Route path="sessions/:id" element={<SessionDetail />} />
+            <Route
+              index
+              element={
+                <Page>
+                  <Dashboard />
+                </Page>
+              }
+            />
+            <Route
+              path="sessions"
+              element={
+                <Page>
+                  <History />
+                </Page>
+              }
+            />
+            <Route
+              path="sessions/:id"
+              element={
+                <Page>
+                  <SessionDetailRoute />
+                </Page>
+              }
+            />
+            <Route
+              path="snapshot/:token"
+              element={
+                <Page>
+                  <SnapshotView />
+                </Page>
+              }
+            />
+            <Route path="query" element={<Navigate to="/sessions?view=agents" replace />} />
            <Route path="activity" element={<Navigate to="/sessions?view=events" replace />} />
-            <Route path="workflows" element={<Workflows />} />
+            <Route
+              path="workflows"
+              element={<Navigate to="/?tab=analytics&sub=workflow" replace />}
+            />
            <Route path="lanes" element={<Navigate to="/workspace" replace />} />
            <Route
              path="cc-config"
-              element={<Navigate to="/settings?tool=claude-code" replace />}
+              element={<Navigate to="/settings/agents/claude-code" replace />}
            />
            <Route path="run" element={<Navigate to="/workspace" replace />} />
-            <Route path="workspace" element={<Workspace />} />
-            <Route path="settings" element={<SettingsHub />} />
+            <Route
+              path="workspace"
+              element={
+                <Page>
+                  <Workspace />
+                </Page>
+              }
+            />
+            <Route
+              path="artifacts"
+              element={
+                <Page>
+                  <Artifacts />
+                </Page>
+              }
+            />
+            <Route
+              path="files"
+              element={
+                <ServerOnly>
+                  <Page>
+                    <FilesPage />
+                  </Page>
+                </ServerOnly>
+              }
+            />
+            <Route
+              path="admin"
+              element={
+                <Page>
+                  <Administration />
+                </Page>
+              }
+            />
+            {/* The Users page became Administration's first tab. */}
+            <Route path="users" element={<Navigate to="/admin" replace />} />
+            <Route
+              path="settings/*"
+              element={
+                <Page>
+                  <SettingsHub />
+                </Page>
+              }
+            />
            <Route path="*" element={<NotFound />} />
          </Route>
        </Routes>
@@ -1,6 +1,6 @@
 /**
 * @file AgentCard.tsx
- * @description Defines the AgentCard component that displays a summary of an agent's information, including its name, status, task, current tool, and timestamps. The card is clickable and navigates to the agent's session details when clicked. It also visually distinguishes active agents with a border highlight.
+ * @description Defines the AgentCard component that displays a summary of an agent's information, including its name, status, task, current tool, and timestamps. The card is clickable and navigates to the agent's session details when clicked; a right-click opens `SessionRowMenu`. It also visually distinguishes active agents with a border highlight.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
 /* =============================================================================
@@ -49,8 +49,11 @@

 import { useTranslation } from "react-i18next";
 import { Bot, GitBranch, Clock, Wrench, Cpu, Coins } from "lucide-react";
-import { useNavigate } from "react-router-dom";
+import { memo, useMemo } from "react";
+import { Link, useNavigate } from "react-router-dom";
 import { AgentStatusBadge } from "./StatusBadge";
+import { useContextMenu } from "./ContextMenu";
+import { SessionRowMenu } from "./SessionRowMenu";
 import { effectiveAgentStatus, isAgentAwaitingInput, agentAwaitingReason } from "../lib/types";
 import type { Agent, Session } from "../lib/types";
 import { formatDuration, timeAgo, formatModelName, pathBasename, fmtCost } from "../lib/format";
@@ -80,9 +83,17 @@ interface AgentCardProps {
  onClick?: () => void;
 }

-export function AgentCard({ agent, session, label, onClick }: AgentCardProps) {
+/** Memoized: the Dashboard re-renders on every live update, and a card only
+ *  changes with its own agent/session. */
+export const AgentCard = memo(function AgentCard({
+  agent,
+  session,
+  label,
+  onClick,
+}: AgentCardProps) {
  const navigate = useNavigate();
  const { t } = useTranslation("kanban");
+  const ctx = useContextMenu<true>();
  const isWaiting = agent.status === "waiting" || isAgentAwaitingInput(agent);
  const status = effectiveAgentStatus(agent);
  const isActive = agent.status === "working";
@@ -116,15 +127,15 @@ export function AgentCard({ agent, session, label, onClick }: AgentCardProps) {
  // not the parent session's — see issue #185). Use it everywhere this card
  // shows a model so a Haiku QA agent under an Opus orchestrator reads as
  // Haiku, not Opus. Falls back to the session model only for the main agent.
-  let subagentModel: string | null = null;
-  if (!isMain && agent.metadata) {
+  const subagentModel = useMemo(() => {
+    if (isMain || !agent.metadata) return null;
    try {
      const parsed = JSON.parse(agent.metadata) as { model?: string };
-      subagentModel = parsed?.model ? formatModelName(parsed.model) : null;
+      return parsed?.model ? formatModelName(parsed.model) : null;
    } catch {
-      subagentModel = null;
+      return null;
    }
-  }
+  }, [isMain, agent.metadata]);
  // The model badge (footer) must reflect THIS card's agent: the session model
  // for main, the subagent's own model for subagents.
  const displayModel = isMain ? model : subagentModel;
@@ -140,15 +151,15 @@ export function AgentCard({ agent, session, label, onClick }: AgentCardProps) {
  // "29 agents" looks like it should equal a 29-subagent stat when the session
  // actually has 28 subagents + 1 main.
  const subagentCount = Math.max(0, agentCount - 1);
-  let sessionTurns = 0;
-  if (isMain && session?.metadata) {
+  const sessionTurns = useMemo(() => {
+    if (!isMain || !session?.metadata) return 0;
    try {
      const m = JSON.parse(session.metadata) as { turn_count?: number };
-      if (typeof m?.turn_count === "number") sessionTurns = m.turn_count;
+      return typeof m?.turn_count === "number" ? m.turn_count : 0;
    } catch {
-      sessionTurns = 0;
+      return 0;
    }
-  }
+  }, [isMain, session?.metadata]);
  const subtitle = isMain
    ? [
        cwdBase,
@@ -159,22 +170,27 @@ export function AgentCard({ agent, session, label, onClick }: AgentCardProps) {
        .join(" · ") || null
    : [label || agent.subagent_type, cwdBase].filter(Boolean).join(" · ") || null;

-  function handleClick() {
-    if (onClick) {
-      onClick();
-    } else {
-      navigate(`/sessions/${agent.session_id}`);
-    }
+  const sessionHref = `/sessions/${agent.session_id}`;
+  // The whole card is clickable with the mouse; the title is the focusable
+  // control (a real link, or a button when the caller handles the click).
+  function handleClick(e: React.MouseEvent) {
+    if ((e.target as HTMLElement).closest("a,button")) return;
+    if (onClick) onClick();
+    else navigate(sessionHref);
  }
+  const titleText = isMain ? mainAgentDisplayName(agent.name, realSessionName) : agent.name;
+  const titleClass =
+    "block text-sm font-medium text-fg-secondary truncate text-left max-w-full rounded focus-visible:outline focus-visible:outline-2 focus-visible:outline-accent";

  return (
    <div
      onClick={handleClick}
+      onContextMenu={(e) => ctx.open(e, true)}
      className={`card-hover p-4 cursor-pointer overflow-hidden ${
        isWaiting
-          ? "border-l-2 border-l-yellow-500/60"
+          ? "border-l-2 border-l-status-warning/60"
          : isActive
-            ? "border-l-2 border-l-emerald-500/50"
+            ? "border-l-2 border-l-status-success/50"
            : ""
      }`}
    >
@@ -182,19 +198,25 @@ export function AgentCard({ agent, session, label, onClick }: AgentCardProps) {
        <div className="flex items-center gap-2.5 min-w-0 overflow-hidden">
          <div
            className={`w-7 h-7 rounded-md flex items-center justify-center flex-shrink-0 ${
-              isMain ? "bg-accent/15 text-accent" : "bg-violet-500/15 text-violet-400"
+              isMain ? "bg-accent/15 text-accent" : "bg-syntax-keyword/15 text-syntax-keyword"
            }`}
          >
            {isMain ? <Bot className="w-3.5 h-3.5" /> : <GitBranch className="w-3.5 h-3.5" />}
          </div>
          <div className="min-w-0 overflow-hidden">
-            <p className="text-sm font-medium text-fg-secondary truncate">
-              {/* Auto-generated main-agent titles (e.g. "Main Agent - Session
-                  229d93fd" or "Main Agent - work - e3f8e613") swap the
-                  placeholder for the real session name when one exists; custom
-                  (sub)agent names are left untouched. */}
-              {isMain ? mainAgentDisplayName(agent.name, realSessionName) : agent.name}
-            </p>
+            {/* Auto-generated main-agent titles (e.g. "Main Agent - Session
+                229d93fd" or "Main Agent - work - e3f8e613") swap the
+                placeholder for the real session name when one exists; custom
+                (sub)agent names are left untouched. */}
+            {onClick ? (
+              <button type="button" onClick={onClick} className={titleClass}>
+                {titleText}
+              </button>
+            ) : (
+              <Link to={sessionHref} className={titleClass}>
+                {titleText}
+              </Link>
+            )}
            {subtitle && <p className="text-[11px] text-fg-muted truncate">{subtitle}</p>}
          </div>
        </div>
@@ -245,11 +267,19 @@ export function AgentCard({ agent, session, label, onClick }: AgentCardProps) {
            {timeAgo(agent.updated_at || agent.started_at)}
          </span>
        )}
-        <span className="ml-auto flex items-center gap-1 min-w-0 opacity-50">
+        <span className="ml-auto flex items-center gap-1 min-w-0">
          {realSessionName && <span className="truncate max-w-[10rem]">{realSessionName} ·</span>}
          <span className="font-mono flex-shrink-0">{agent.session_id.slice(0, 8)}</span>
        </span>
      </div>
+      {ctx.menu && (
+        <SessionRowMenu
+          session={{ id: agent.session_id, lane_id: session?.lane_id, cwd: session?.cwd }}
+          x={ctx.menu.x}
+          y={ctx.menu.y}
+          onClose={ctx.close}
+        />
+      )}
    </div>
  );
-}
+});
@@ -0,0 +1,56 @@
+/**
+ * @file AiToolIcon.tsx
+ * @description An AI tool's icon: the mark shipped in `client/public/ai-tools/`
+ * when there is one, else
+ * the server's cached favicon (GET /api/ai-tools/:id/icon), else the label's
+ * first letter. Every tool icon in the app renders through here.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useState } from "react";
+import { api, type AiTool } from "../lib/api";
+
+/** Shipped marks by tool id. */
+const BUNDLED: Record<string, string> = {
+  claude: "/ai-tools/claude.svg",
+  codex: "/ai-tools/codex.svg",
+  gemini: "/ai-tools/gemini.svg",
+  openclaw: "/ai-tools/openclaw.svg",
+  hermes: "/ai-tools/hermes.svg",
+};
+
+/**
+ * @param props.tool - The catalog entry.
+ * @param props.className - Size classes (default `h-8 w-8`).
+ */
+export function AiToolIcon({
+  tool,
+  className = "h-8 w-8",
+}: {
+  tool: Pick<AiTool, "id" | "label">;
+  className?: string;
+}) {
+  // Keyed by id: one instance showing another tool must retry its icon.
+  const [failedId, setFailedId] = useState<string | null>(null);
+  const box = `${className} shrink-0 rounded-md bg-surface-4 object-contain p-1`;
+  const bundled = BUNDLED[tool.id];
+  if (bundled) return <img src={bundled} alt="" className={box} />;
+  if (failedId !== tool.id) {
+    return (
+      <img
+        src={api.aiTools.iconUrl(tool.id)}
+        alt=""
+        onError={() => setFailedId(tool.id)}
+        className={box}
+      />
+    );
+  }
+  return (
+    <span
+      aria-hidden
+      className={`${className} flex shrink-0 items-center justify-center rounded-md bg-surface-4 text-xs font-semibold text-fg-secondary`}
+    >
+      {tool.label.charAt(0).toUpperCase()}
+    </span>
+  );
+}
@@ -8,6 +8,7 @@
 *   • Activity - the live fired-alert feed with acknowledge controls
 * Tab badges reflect live state (rule count, unacked alert count), and the feed
 * + counts refetch on alert_triggered / alert_updated WebSocket messages.
+ * A right-click on a rule opens its Enable/Disable and Delete as a menu.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
 /* =============================================================================
@@ -70,7 +71,9 @@ import {
  Check,
  CheckCheck,
  ChevronDown,
+  Eye,
  ListChecks,
+  Pencil,
  Plus,
  RefreshCw,
  Trash2,
@@ -85,8 +88,13 @@ import { WebhookSettings } from "./WebhookSettings";
 import { ConfirmModal } from "./ConfirmModal";
 import { Checkbox } from "./Checkbox";
 import { FieldHelp } from "./FieldHelp";
-import { timeAgo } from "../lib/format";
-import type { AlertEvent, AlertRule, AlertRuleType, WSMessage } from "../lib/types";
+import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "./ContextMenu";
+import { fmtCost, timeAgo } from "../lib/format";
+import { toast } from "../lib/toast";
+import { useAiTools } from "../hooks/useAiTools";
+import { useSpin } from "../hooks/useSpin";
+import { usePermissions } from "./AuthGate";
+import type { AlertEvent, AlertRule, AlertRuleType, RulePreview, WSMessage } from "../lib/types";

 const PAGE_SIZE = 25;

@@ -121,6 +129,8 @@ const RULE_TYPES: AlertRuleType[] = [
  "inactivity",
  "status_duration",
  "token_threshold",
+  "cost_threshold",
+  "budget",
 ];

 type TabKey = "rules" | "channels" | "activity";
@@ -136,6 +146,11 @@ interface RuleFormState {
  minutes: string;
  status: "working" | "waiting";
  total_tokens: string;
+  usd: string;
+  period: "day" | "week" | "month";
+  limit_usd: string;
+  thresholds: string;
+  budget_tool: string;
  cooldown_seconds: string;
 }

@@ -150,9 +165,51 @@ const EMPTY_FORM: RuleFormState = {
  minutes: "10",
  status: "working",
  total_tokens: "1000000",
+  usd: "5",
+  period: "month",
+  limit_usd: "100",
+  thresholds: "80, 100",
+  budget_tool: "",
  cooldown_seconds: "300",
 };

+/** A rule's stored values as form fields, for editing it. */
+function formFromRule(rule: AlertRule): RuleFormState {
+  const c = rule.config;
+  const str = (v: unknown, fallback: string) => (v == null ? fallback : String(v));
+  return {
+    name: rule.name,
+    rule_type: rule.rule_type,
+    event_type: str(c.event_type, ""),
+    tool_name: str(c.tool_name, ""),
+    summary_contains: str(c.summary_contains, ""),
+    count: str(c.count, EMPTY_FORM.count),
+    window_minutes: str(c.window_minutes, EMPTY_FORM.window_minutes),
+    minutes: str(c.minutes, EMPTY_FORM.minutes),
+    status: c.status === "waiting" ? "waiting" : "working",
+    total_tokens: str(c.total_tokens, EMPTY_FORM.total_tokens),
+    usd: str(c.usd, EMPTY_FORM.usd),
+    period: c.period === "day" || c.period === "week" ? c.period : "month",
+    limit_usd: str(c.limit_usd, EMPTY_FORM.limit_usd),
+    thresholds: Array.isArray(c.thresholds) ? c.thresholds.join(", ") : EMPTY_FORM.thresholds,
+    budget_tool: str(c.tool, ""),
+    cooldown_seconds: String(rule.cooldown_seconds),
+  };
+}
+
+const errText = (err: unknown) => (err instanceof Error ? err.message : String(err));
+
+/** "80, 100" → [80, 100]; null when any part is not a whole percent 1..1000. */
+function parseThresholds(text: string): number[] | null {
+  const parts = text
+    .split(",")
+    .map((p) => p.trim())
+    .filter(Boolean);
+  const nums = parts.map((p) => Number(p));
+  if (nums.length === 0 || nums.length > 10) return null;
+  return nums.every((n) => Number.isInteger(n) && n > 0 && n <= 1000) ? nums : null;
+}
+
 function buildConfig(form: RuleFormState): AlertRule["config"] {
  switch (form.rule_type) {
    case "event_pattern": {
@@ -174,6 +231,18 @@ function buildConfig(form: RuleFormState): AlertRule["config"] {
      return { status: form.status, minutes: parseFloat(form.minutes) };
    case "token_threshold":
      return { total_tokens: parseInt(form.total_tokens, 10) };
+    case "cost_threshold":
+      return { usd: parseFloat(form.usd) };
+    case "budget": {
+      const config: AlertRule["config"] = {
+        period: form.period,
+        limit_usd: parseFloat(form.limit_usd),
+        thresholds: parseThresholds(form.thresholds) ?? [80, 100],
+        tz_offset: new Date().getTimezoneOffset(),
+      };
+      if (form.budget_tool) config.tool = form.budget_tool;
+      return config;
+    }
  }
 }

@@ -201,6 +270,14 @@ function describeRule(rule: AlertRule, t: (key: string, opts?: Record<string, un
      return t("ruleDesc.statusDuration", { status: c.status, minutes: c.minutes });
    case "token_threshold":
      return t("ruleDesc.tokenThreshold", { tokens: (c.total_tokens ?? 0).toLocaleString() });
+    case "cost_threshold":
+      return t("ruleDesc.costThreshold", { usd: fmtCost(c.usd ?? 0) });
+    case "budget":
+      return t("ruleDesc.budget", {
+        limit: fmtCost(c.limit_usd ?? 0),
+        period: t(`periods.${c.period ?? "month"}`),
+        thresholds: (c.thresholds ?? []).join("%, ") + "%",
+      });
  }
 }

@@ -208,16 +285,30 @@ export function AlertsNotifications() {
  const { t } = useTranslation("alerts");
  const { t: ts } = useTranslation("settings");

-  const [tab, setTab] = useState<TabKey>("rules");
+  // Rules and channels (webhooks) fire for every user's sessions: an admin's.
+  const { isAdmin } = usePermissions();
+  const [tab, setTab] = useState<TabKey>(isAdmin ? "rules" : "activity");

  // Rules
  const [rules, setRules] = useState<AlertRule[]>([]);
  const [loadingRules, setLoadingRules] = useState(true);
  const [formOpen, setFormOpen] = useState(false);
  const [form, setForm] = useState<RuleFormState>(EMPTY_FORM);
+  // The rule being edited, or null while the form creates a new one.
+  const [editingId, setEditingId] = useState<string | null>(null);
  const [formError, setFormError] = useState<string | null>(null);
  const [saving, setSaving] = useState(false);
  const [confirmRule, setConfirmRule] = useState<AlertRule | null>(null);
+  const [preview, setPreview] = useState<RulePreview | null>(null);
+  const [previewing, setPreviewing] = useState(false);
+  const aiTools = useAiTools();
+  const ruleCtx = useContextMenu<AlertRule>();
+  // A rule-menu item: close the menu, then act on the rule it was opened on.
+  const pickRule = (fn: (rule: AlertRule) => unknown) => () => {
+    const rule = ruleCtx.menu?.item;
+    ruleCtx.close();
+    if (rule) fn(rule);
+  };

  // Feed
  const [alerts, setAlerts] = useState<AlertEvent[]>([]);
@@ -232,11 +323,11 @@ export function AlertsNotifications() {
      const res = await api.alerts.rules.list();
      setRules(res.rules);
    } catch (err) {
-      console.error("Failed to load alert rules:", err);
+      toast.error(t("errors.loadRules", { error: errText(err) }));
    } finally {
      setLoadingRules(false);
    }
-  }, []);
+  }, [t]);

  const loadAlerts = useCallback(async () => {
    setLoadingAlerts(true);
@@ -250,11 +341,12 @@ export function AlertsNotifications() {
      setTotal(res.total);
      setUnacked(res.unacked);
    } catch (err) {
-      console.error("Failed to load alerts:", err);
+      toast.error(t("errors.loadAlerts", { error: errText(err) }));
    } finally {
      setLoadingAlerts(false);
    }
-  }, [unackedOnly]);
+  }, [unackedOnly, t]);
+  const [spinning, refreshAlerts] = useSpin(loadAlerts);

  const loadMore = useCallback(async () => {
    try {
@@ -267,13 +359,13 @@ export function AlertsNotifications() {
      setTotal(res.total);
      setUnacked(res.unacked);
    } catch (err) {
-      console.error("Failed to load more alerts:", err);
+      toast.error(t("errors.loadAlerts", { error: errText(err) }));
    }
-  }, [unackedOnly, alerts.length]);
+  }, [unackedOnly, alerts.length, t]);

  useEffect(() => {
-    loadRules();
-  }, [loadRules]);
+    if (isAdmin) loadRules();
+  }, [loadRules, isAdmin]);

  useEffect(() => {
    loadAlerts();
@@ -289,22 +381,61 @@ export function AlertsNotifications() {
    });
  }, [loadAlerts]);

-  const set = (patch: Partial<RuleFormState>) => setForm((prev) => ({ ...prev, ...patch }));
+  // Any edit makes a shown preview stale.
+  const set = (patch: Partial<RuleFormState>) => {
+    setPreview(null);
+    setForm((prev) => ({ ...prev, ...patch }));
+  };

-  const onCreateRule = async () => {
-    if (saving) return;
-    setSaving(true);
+  const onPreview = async () => {
+    if (previewing) return;
+    setPreviewing(true);
    setFormError(null);
    try {
      const cooldown = parseInt(form.cooldown_seconds, 10);
-      await api.alerts.rules.create({
+      setPreview(
+        await api.alerts.rules.preview({
+          rule_type: form.rule_type,
+          config: buildConfig(form),
+          cooldown_seconds: Number.isFinite(cooldown) && cooldown >= 0 ? cooldown : 300,
+        })
+      );
+    } catch (err) {
+      setFormError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setPreviewing(false);
+    }
+  };
+
+  const closeForm = () => {
+    setForm(EMPTY_FORM);
+    setPreview(null);
+    setEditingId(null);
+    setFormOpen(false);
+    setFormError(null);
+  };
+
+  const openEditRule = (rule: AlertRule) => {
+    setForm(formFromRule(rule));
+    setPreview(null);
+    setEditingId(rule.id);
+    setFormError(null);
+    setFormOpen(true);
+  };
+
+  const onSaveRule = async () => {
+    if (saving || !canSubmit) return;
+    setSaving(true);
+    setFormError(null);
+    try {
+      const body = {
        name: form.name.trim(),
-        rule_type: form.rule_type,
        config: buildConfig(form),
-        cooldown_seconds: Number.isFinite(cooldown) && cooldown >= 0 ? cooldown : 300,
-      });
-      setForm(EMPTY_FORM);
-      setFormOpen(false);
+        cooldown_seconds: cooldownVal,
+      };
+      if (editingId) await api.alerts.rules.update(editingId, body);
+      else await api.alerts.rules.create({ ...body, rule_type: form.rule_type });
+      closeForm();
      loadRules();
    } catch (err) {
      setFormError(err instanceof Error ? err.message : String(err));
@@ -318,7 +449,7 @@ export function AlertsNotifications() {
      await api.alerts.rules.update(rule.id, { enabled: !rule.enabled });
      loadRules();
    } catch (err) {
-      console.error("Failed to toggle alert rule:", err);
+      toast.error(t("errors.toggleRule", { error: errText(err) }));
    }
  };

@@ -329,7 +460,8 @@ export function AlertsNotifications() {
      loadRules();
      loadAlerts();
    } catch (err) {
-      console.error("Failed to delete alert rule:", err);
+      setConfirmRule(null);
+      toast.error(t("errors.deleteRule", { error: errText(err) }));
    }
  };

@@ -338,7 +470,7 @@ export function AlertsNotifications() {
      await api.alerts.ack(id);
      loadAlerts();
    } catch (err) {
-      console.error("Failed to acknowledge alert:", err);
+      toast.error(t("errors.ack", { error: errText(err) }));
    }
  };

@@ -347,7 +479,7 @@ export function AlertsNotifications() {
      await api.alerts.ackAll();
      loadAlerts();
    } catch (err) {
-      console.error("Failed to acknowledge alerts:", err);
+      toast.error(t("errors.ack", { error: errText(err) }));
    }
  };

@@ -357,8 +489,12 @@ export function AlertsNotifications() {
  const tokensVal = parseInt(form.total_tokens, 10);
  const countVal = parseInt(form.count, 10);
  const windowVal = parseFloat(form.window_minutes);
+  // Cooldown is a whole number of seconds ≥ 0 — never silently replaced by 300.
+  const cooldownOk = /^\d+$/.test(form.cooldown_seconds.trim());
+  const cooldownVal = cooldownOk ? parseInt(form.cooldown_seconds, 10) : 0;
  const canSubmit =
    form.name.trim().length > 0 &&
+    cooldownOk &&
    (form.rule_type !== "event_pattern" ||
      (Boolean(form.event_type.trim() || form.tool_name.trim() || form.summary_contains.trim()) &&
        Number.isFinite(countVal) &&
@@ -366,9 +502,12 @@ export function AlertsNotifications() {
        (countVal <= 1 || (Number.isFinite(windowVal) && windowVal > 0)))) &&
    ((form.rule_type !== "inactivity" && form.rule_type !== "status_duration") ||
      (Number.isFinite(minutesVal) && minutesVal > 0)) &&
-    (form.rule_type !== "token_threshold" || (Number.isFinite(tokensVal) && tokensVal > 0));
+    (form.rule_type !== "token_threshold" || (Number.isFinite(tokensVal) && tokensVal > 0)) &&
+    (form.rule_type !== "cost_threshold" || parseFloat(form.usd) > 0) &&
+    (form.rule_type !== "budget" ||
+      (parseFloat(form.limit_usd) > 0 && parseThresholds(form.thresholds) !== null));

-  const TABS: { key: TabKey; label: string; icon: typeof ListChecks; badge?: number }[] = [
+  const ALL_TABS: { key: TabKey; label: string; icon: typeof ListChecks; badge?: number }[] = [
    {
      key: "rules",
      label: ts("alertsHub.tabRules"),
@@ -383,6 +522,7 @@ export function AlertsNotifications() {
      badge: unacked || undefined,
    },
  ];
+  const TABS = isAdmin ? ALL_TABS : ALL_TABS.filter((tb) => tb.key === "activity");

  return (
    <div className="space-y-4">
@@ -431,8 +571,11 @@ export function AlertsNotifications() {
            </div>
            <button
              onClick={() => {
-                setFormOpen((open) => !open);
-                setFormError(null);
+                if (formOpen) closeForm();
+                else {
+                  setFormOpen(true);
+                  setFormError(null);
+                }
              }}
              className="btn-ghost border border-border inline-flex items-center gap-1.5 text-xs flex-shrink-0"
            >
@@ -466,7 +609,9 @@ export function AlertsNotifications() {
                    <select
                      value={form.rule_type}
                      onChange={(e) => set({ rule_type: e.target.value as AlertRuleType })}
-                      className="input w-full appearance-none pr-8"
+                      disabled={!!editingId}
+                      title={editingId ? t("rules.typeFixed") : undefined}
+                      className="select w-full"
                    >
                      {RULE_TYPES.map((type) => (
                        <option key={type} value={type}>
@@ -474,7 +619,6 @@ export function AlertsNotifications() {
                        </option>
                      ))}
                    </select>
-                    <ChevronDown className="w-3.5 h-3.5 absolute right-2.5 top-1/2 -translate-y-1/2 text-fg-muted pointer-events-none" />
                  </div>
                </label>
              </div>
@@ -577,12 +721,11 @@ export function AlertsNotifications() {
                        <select
                          value={form.status}
                          onChange={(e) => set({ status: e.target.value as "working" | "waiting" })}
-                          className="input w-full appearance-none pr-8"
+                          className="select w-full"
                        >
                          <option value="working">working</option>
                          <option value="waiting">waiting</option>
                        </select>
-                        <ChevronDown className="w-3.5 h-3.5 absolute right-2.5 top-1/2 -translate-y-1/2 text-fg-muted pointer-events-none" />
                      </div>
                    </label>
                  )}
@@ -626,6 +769,100 @@ export function AlertsNotifications() {
                </div>
              )}

+              {form.rule_type === "cost_threshold" && (
+                <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
+                  <label className="block text-xs text-fg-secondary">
+                    <span className="inline-flex items-center gap-1">
+                      {t("rules.form.usd")}
+                      <FieldHelp description={t("rules.help.usd")} />
+                    </span>
+                    <input
+                      type="number"
+                      min={0}
+                      step="0.01"
+                      value={form.usd}
+                      onChange={(e) => set({ usd: e.target.value })}
+                      className="input mt-1 w-full"
+                    />
+                  </label>
+                </div>
+              )}
+
+              {form.rule_type === "budget" && (
+                <div className="grid grid-cols-1 sm:grid-cols-4 gap-3">
+                  <label className="block text-xs text-fg-secondary">
+                    <span className="inline-flex items-center gap-1">
+                      {t("rules.form.period")}
+                      <FieldHelp description={t("rules.help.period")} />
+                    </span>
+                    <div className="relative mt-1">
+                      <select
+                        value={form.period}
+                        onChange={(e) => set({ period: e.target.value as RuleFormState["period"] })}
+                        className="input w-full appearance-none pr-8"
+                      >
+                        {(["day", "week", "month"] as const).map((p) => (
+                          <option key={p} value={p}>
+                            {t(`periods.${p}`)}
+                          </option>
+                        ))}
+                      </select>
+                      <ChevronDown className="w-3.5 h-3.5 absolute right-2.5 top-1/2 -translate-y-1/2 text-fg-muted pointer-events-none" />
+                    </div>
+                  </label>
+                  <label className="block text-xs text-fg-secondary">
+                    <span className="inline-flex items-center gap-1">
+                      {t("rules.form.limitUsd")}
+                      <FieldHelp description={t("rules.help.limitUsd")} />
+                    </span>
+                    <input
+                      type="number"
+                      min={0}
+                      step="0.01"
+                      value={form.limit_usd}
+                      onChange={(e) => set({ limit_usd: e.target.value })}
+                      className="input mt-1 w-full"
+                    />
+                  </label>
+                  <label className="block text-xs text-fg-secondary">
+                    <span className="inline-flex items-center gap-1">
+                      {t("rules.form.thresholds")}
+                      <FieldHelp description={t("rules.help.thresholds")} />
+                    </span>
+                    <input
+                      type="text"
+                      value={form.thresholds}
+                      onChange={(e) => set({ thresholds: e.target.value })}
+                      placeholder="80, 100"
+                      className="input mt-1 w-full"
+                    />
+                  </label>
+                  <label className="block text-xs text-fg-secondary">
+                    <span className="inline-flex items-center gap-1">
+                      {t("rules.form.budgetTool")}
+                      <FieldHelp description={t("rules.help.budgetTool")} />
+                    </span>
+                    <div className="relative mt-1">
+                      <select
+                        value={form.budget_tool}
+                        onChange={(e) => set({ budget_tool: e.target.value })}
+                        className="input w-full appearance-none pr-8"
+                      >
+                        <option value="">{t("rules.form.allTools")}</option>
+                        {aiTools.tools.map((x) => (
+                          <option key={x.id} value={x.id}>
+                            {x.label}
+                          </option>
+                        ))}
+                      </select>
+                      <ChevronDown className="w-3.5 h-3.5 absolute right-2.5 top-1/2 -translate-y-1/2 text-fg-muted pointer-events-none" />
+                    </div>
+                  </label>
+                </div>
+              )}
+
+              {preview && <RulePreviewResult preview={preview} />}
+
              <div className="flex flex-wrap items-end justify-between gap-3">
                <label className="block text-xs text-fg-secondary">
                  <span className="mb-1.5 flex items-center gap-1">
@@ -635,19 +872,41 @@ export function AlertsNotifications() {
                  <input
                    type="number"
                    min={0}
+                    step={1}
                    value={form.cooldown_seconds}
                    onChange={(e) => set({ cooldown_seconds: e.target.value })}
+                    aria-invalid={!cooldownOk}
                    className="input w-40"
                  />
+                  {!cooldownOk && (
+                    <span className="mt-1 block text-[11px] text-status-danger">
+                      {t("rules.cooldownInvalid")}
+                    </span>
+                  )}
                </label>
-                <button
-                  onClick={onCreateRule}
-                  disabled={!canSubmit || saving}
-                  className="btn-primary inline-flex items-center gap-2 text-sm disabled:opacity-50 disabled:cursor-not-allowed"
-                >
-                  <Plus className="w-3.5 h-3.5" />
-                  {saving ? t("rules.saving") : t("rules.create")}
-                </button>
+                <div className="flex items-center gap-2">
+                  <button
+                    onClick={onPreview}
+                    disabled={!canSubmit || previewing}
+                    title={t("rules.previewHint")}
+                    className="btn-ghost border border-border inline-flex items-center gap-2 text-sm disabled:opacity-50 disabled:cursor-not-allowed"
+                  >
+                    <Eye className="w-3.5 h-3.5" />
+                    {previewing ? t("rules.previewing") : t("rules.preview")}
+                  </button>
+                  <button
+                    onClick={onSaveRule}
+                    disabled={!canSubmit || saving}
+                    className="btn-primary inline-flex items-center gap-2 text-sm disabled:opacity-50 disabled:cursor-not-allowed"
+                  >
+                    {editingId ? (
+                      <Check className="w-3.5 h-3.5" />
+                    ) : (
+                      <Plus className="w-3.5 h-3.5" />
+                    )}
+                    {saving ? t("rules.saving") : editingId ? t("rules.save") : t("rules.create")}
+                  </button>
+                </div>
              </div>
              {formError && <p className="text-xs text-status-danger">{formError}</p>}
            </div>
@@ -663,12 +922,14 @@ export function AlertsNotifications() {
              icon={ListChecks}
              title={t("rules.empty")}
              description={ts("alertsHub.rulesEmptyHint")}
+              compact
            />
          ) : (
            <ul className="space-y-2">
              {rules.map((rule) => (
                <li
                  key={rule.id}
+                  onContextMenu={(e) => ruleCtx.open(e, rule)}
                  className="flex flex-wrap items-center justify-between gap-3 rounded-lg border border-border bg-surface-2 px-3 py-2.5"
                >
                  <div className="min-w-0">
@@ -699,6 +960,14 @@ export function AlertsNotifications() {
                    >
                      {rule.enabled ? t("rules.enabled") : t("rules.disabled")}
                    </button>
+                    <button
+                      onClick={() => openEditRule(rule)}
+                      className="p-1.5 rounded-md text-fg-muted hover:text-fg-primary hover:bg-surface-3 transition-colors"
+                      title={t("rules.edit")}
+                      aria-label={t("rules.edit")}
+                    >
+                      <Pencil className="w-3.5 h-3.5" />
+                    </button>
                    <button
                      onClick={() => setConfirmRule(rule)}
                      className="p-1.5 rounded-md text-fg-muted hover:text-status-danger hover:bg-status-danger/10 transition-colors"
@@ -712,6 +981,23 @@ export function AlertsNotifications() {
              ))}
            </ul>
          )}
+          {ruleCtx.menu && (
+            <ContextMenu
+              x={ruleCtx.menu.x}
+              y={ruleCtx.menu.y}
+              onClose={ruleCtx.close}
+              testId="alert-rule-menu"
+            >
+              <MenuItem onSelect={pickRule(onToggleRule)}>
+                {ruleCtx.menu.item.enabled ? t("rules.disable") : t("rules.enable")}
+              </MenuItem>
+              <MenuItem onSelect={pickRule(openEditRule)}>{t("rules.edit")}</MenuItem>
+              <MenuSeparator />
+              <MenuItem danger onSelect={pickRule(setConfirmRule)}>
+                {t("rules.delete")}
+              </MenuItem>
+            </ContextMenu>
+          )}
        </div>
      )}

@@ -737,11 +1023,13 @@ export function AlertsNotifications() {
                label={t("feed.unackedOnly")}
              />
              <button
-                onClick={() => loadAlerts()}
+                onClick={refreshAlerts}
+                disabled={spinning}
+                aria-busy={spinning}
                className="btn-ghost border border-border inline-flex items-center gap-1.5 text-xs"
                title={t("refresh")}
              >
-                <RefreshCw className="w-3.5 h-3.5" />
+                <RefreshCw className={`w-3.5 h-3.5 ${spinning ? "animate-spin" : ""}`} />
              </button>
              {unacked > 0 && (
                <button
@@ -766,6 +1054,7 @@ export function AlertsNotifications() {
              icon={unackedOnly ? BellOff : BellRing}
              title={t("feed.emptyTitle")}
              description={unackedOnly ? t("feed.emptyUnacked") : t("feed.emptyDescription")}
+              compact
            />
          ) : (
            <>
@@ -801,7 +1090,7 @@ export function AlertsNotifications() {
                        )}
                      </p>
                    </div>
-                    {!alert.acknowledged_at && (
+                    {!alert.acknowledged_at && alert.can_ack !== false && (
                      <button
                        onClick={() => onAck(alert.id)}
                        className="inline-flex items-center gap-1.5 text-xs px-2.5 py-1.5 rounded-md border border-border text-fg-secondary hover:text-fg-primary hover:bg-surface-3 transition-colors flex-shrink-0"
@@ -838,3 +1127,51 @@ export function AlertsNotifications() {
    </div>
  );
 }
+
+/** What a rule would have fired, from POST /api/alerts/rules/preview. */
+function RulePreviewResult({ preview }: { preview: RulePreview }) {
+  const { t } = useTranslation("alerts");
+  if (!preview.supported) {
+    return <p className="text-xs text-fg-muted">{t("rules.previewUnsupported")}</p>;
+  }
+  if (preview.periods) {
+    return (
+      <div className="rounded-md border border-border bg-surface-1 p-2 text-xs space-y-1">
+        <p className="text-fg-secondary">{t("rules.previewBudget")}</p>
+        {preview.periods.map((p) => (
+          <div key={p.period_start} className="flex justify-between gap-3 font-mono">
+            <span className="text-fg-muted">{p.period_start}</span>
+            <span className="text-fg-secondary">
+              {fmtCost(p.spend)} · {Math.round(p.pct)}%
+            </span>
+            <span className={p.crossed.length ? "text-status-warning" : "text-fg-muted"}>
+              {p.crossed.length ? p.crossed.map((c) => `${c}%`).join(" ") : "—"}
+            </span>
+          </div>
+        ))}
+      </div>
+    );
+  }
+  return (
+    <div className="rounded-md border border-border bg-surface-1 p-2 text-xs space-y-1">
+      <p className="text-fg-secondary">
+        {t("rules.previewResult", {
+          fires: preview.fires,
+          sessions: preview.sessions,
+          days: preview.window_days,
+        })}
+      </p>
+      {preview.samples.map((s, i) => (
+        <div key={i} className="flex justify-between gap-3 font-mono text-fg-muted">
+          <Link
+            to={`/sessions/${encodeURIComponent(s.session_id)}`}
+            className="truncate hover:text-accent"
+          >
+            {s.session_id.slice(0, 8)}
+          </Link>
+          <span>{timeAgo(s.at)}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
@@ -0,0 +1,286 @@
+/**
+ * @file AuthGate.tsx
+ * @description Server mode's login gate around the whole app (docs/SERVER-MODE.md).
+ * Asks `GET /api/auth/me` (again every 2 s while it gets no answer): in local
+ * mode — the default — it renders the app and nothing else changes, at once
+ * when this browser last saw local mode (`agenthub.authMode`); in server mode it renders the login page until
+ * someone logs in, and again whenever a request answers 401 `EAUTH`
+ * (`AUTH_REQUIRED_EVENT`). Logging out unmounts the app, so no page keeps the
+ * previous user's data. `useAuth()` gives the sidebar the user, `logout`, and
+ * `updateUser` (Settings → Account's saved display name shows at once);
+ * `usePermissions()` says what that user's role may do, so pages hide the rest.
+ * Once an account is known (local mode is one), its own UI preferences are
+ * loaded into this browser (`lib/userPrefs.ts`).
+ * The login page follows the OS's light/dark (`applySystemTheme`).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useState,
+  type FormEvent,
+  type ReactNode,
+} from "react";
+import { useTranslation } from "react-i18next";
+import { Eye, EyeOff } from "lucide-react";
+import { BRAND_LOGO } from "../lib/brand";
+import { applySystemTheme } from "../hooks/useTheme";
+import { api, AUTH_REQUIRED_EVENT, type AuthState, type AuthUser } from "../lib/api";
+import { hydrate } from "../lib/userPrefs";
+
+type AuthValue = {
+  state: AuthState;
+  logout: () => Promise<void>;
+  updateUser: (patch: Partial<AuthUser>) => void;
+};
+
+const AuthContext = createContext<AuthValue>({
+  state: { mode: "local" },
+  logout: async () => {},
+  updateUser: () => {},
+});
+
+/** The current login; `{mode: "local"}` outside server mode (and in tests). */
+export const useAuth = () => useContext(AuthContext);
+
+/**
+ * What the logged-in user may do — the server's rules (server/lib/auth.js,
+ * scope.js) mirrored so the UI hides what would only be refused. Local mode:
+ * everything. `isAdmin`: the host's own setup (Settings → System, updates,
+ * AI tools, proxies, users, alert rules…). `seesAll`: every user's rows
+ * (admin, analyst). `canEditLane`: an admin any workspace, everyone else
+ * only their own — the one that matters is an analyst looking at another
+ * user's.
+ */
+export function usePermissions() {
+  const { state } = useAuth();
+  const user = state.mode === "server" ? state.user : null;
+  const local = state.mode !== "server";
+  const isAdmin = local || user?.role === "admin";
+  return {
+    isAdmin,
+    // Local mode: one person on their own machine — what only serves a
+    // shared server (File Explorer, uploads, AgentHub's own git logins) is
+    // hidden; their desktop and their own git config already do it.
+    local,
+    seesAll: local || (!!user && user.role !== "developer"),
+    // A developer only ever sees their own rows, so everything shown is theirs.
+    canEditLane: (lane?: { owner_id?: number | null } | null) =>
+      isAdmin || user?.role === "developer" || (!!user && lane?.owner_id === user.id),
+  };
+}
+
+/** The mode this browser last saw, so a local dashboard paints at once. */
+const MODE_KEY = "agenthub.authMode";
+const RETRY_MS = 2000;
+
+function cachedState(): AuthState | null {
+  try {
+    return localStorage.getItem(MODE_KEY) === "local" ? { mode: "local" } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function AuthGate({ children }: { children: ReactNode }) {
+  // null = still asking the server. A browser that last saw local mode starts
+  // there and is corrected by the answer (or by a 401) if that changed.
+  const [state, setState] = useState<AuthState | null>(cachedState);
+
+  useEffect(() => {
+    let timer: number | undefined;
+    let alive = true;
+    const ask = () => {
+      api.auth
+        .me()
+        .then((next) => {
+          if (!alive) return;
+          try {
+            localStorage.setItem(MODE_KEY, next.mode);
+          } catch {
+            /* storage blocked */
+          }
+          setState(next);
+        })
+        .catch((err: { status?: number; code?: string }) => {
+          if (!alive) return;
+          // An answer that is not this build's: an older server still running
+          // under a freshly built UI (404, or its index.html → EBADRESPONSE), or
+          // DASHBOARD_TOKEN's own 401 — neither is server mode, so render the
+          // app as before and let it show its own state.
+          if (
+            err?.status === 404 ||
+            err?.code === "EBADRESPONSE" ||
+            (err?.status === 401 && err?.code !== "EAUTH")
+          ) {
+            setState({ mode: "local" });
+            return;
+          }
+          // No answer at all (a restart, a proxy's 502): ask again rather than
+          // guess — "local" would hide a server-mode dashboard's login page.
+          timer = window.setTimeout(ask, RETRY_MS);
+        });
+    };
+    ask();
+    // Any request answering 401 EAUTH means server mode with no valid login.
+    const onRequired = () => setState({ mode: "server", user: null });
+    window.addEventListener(AUTH_REQUIRED_EVENT, onRequired);
+    return () => {
+      alive = false;
+      window.clearTimeout(timer);
+      window.removeEventListener(AUTH_REQUIRED_EVENT, onRequired);
+    };
+  }, []);
+
+  // The signed-in account's own preferences (lib/userPrefs.ts): loaded once
+  // per account, so a second login in this browser brings that account's.
+  const account =
+    state?.mode === "local"
+      ? "local"
+      : state?.mode === "server" && state.user
+        ? `u${state.user.id}`
+        : null;
+  useEffect(() => {
+    if (account) void hydrate();
+  }, [account]);
+
+  // Stable, so a page may list it as an effect dependency.
+  const updateUser = useCallback(
+    (patch: Partial<AuthUser>) =>
+      setState((s) =>
+        s && s.mode === "server" && s.user ? { ...s, user: { ...s.user, ...patch } } : s
+      ),
+    []
+  );
+
+  if (!state) return null;
+  if (state.mode === "server" && !state.user) {
+    return <LoginPage onLoggedIn={(user) => setState({ mode: "server", user })} />;
+  }
+  const logout = async () => {
+    await api.auth.logout().catch(() => {});
+    setState({ mode: "server", user: null });
+  };
+  return (
+    <AuthContext.Provider value={{ state, logout, updateUser }}>{children}</AuthContext.Provider>
+  );
+}
+
+function LoginPage({ onLoggedIn }: { onLoggedIn: (user: AuthUser) => void }) {
+  const { t } = useTranslation();
+  const [username, setUsername] = useState("");
+  const [password, setPassword] = useState("");
+  const [showPassword, setShowPassword] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Nobody is signed in, so no account's theme applies: follow the OS, live.
+  useLayoutEffect(() => {
+    applySystemTheme();
+    const mq = window.matchMedia?.("(prefers-color-scheme: dark)");
+    mq?.addEventListener?.("change", applySystemTheme);
+    return () => mq?.removeEventListener?.("change", applySystemTheme);
+  }, []);
+
+  const submit = async (e: FormEvent) => {
+    e.preventDefault();
+    setBusy(true);
+    setError(null);
+    try {
+      onLoggedIn((await api.auth.login(username, password)).user);
+    } catch (err) {
+      const code = (err as { code?: string }).code;
+      setError(code === "ETOOMANY" ? t("auth.tooMany") : t("auth.failed"));
+      setPassword("");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <main className="flex min-h-screen items-center justify-center bg-surface-0 p-4">
+      <form
+        onSubmit={submit}
+        className="card relative w-full max-w-md overflow-hidden px-6 pb-8 pt-12 sm:px-10"
+      >
+        {/* Accent glow and a grid fading out from the top, drawn from the
+            theme's own accent so it holds in every theme. */}
+        <div
+          aria-hidden
+          className="pointer-events-none absolute inset-x-0 top-0 h-56"
+          style={{
+            backgroundImage:
+              "linear-gradient(to right, rgb(var(--accent) / 0.12) 1px, transparent 1px), linear-gradient(to bottom, rgb(var(--accent) / 0.12) 1px, transparent 1px), radial-gradient(ellipse at top, rgb(var(--accent) / 0.16), transparent 70%)",
+            backgroundSize: "48px 48px, 48px 48px, 100% 100%",
+            backgroundPosition: "center top",
+            maskImage: "radial-gradient(ellipse 70% 100% at top, black 30%, transparent 100%)",
+          }}
+        />
+        <div className="relative space-y-5">
+          <div className="text-center">
+            <img src={BRAND_LOGO} alt="SmartGift" className="block h-auto w-full" />
+            <h1 className="mt-5 text-3xl font-semibold tracking-tight text-fg-primary">
+              {t("auth.title")}
+            </h1>
+            <p className="mt-2 text-sm text-fg-secondary">{t("auth.subtitle")}</p>
+          </div>
+          <label className="block space-y-1.5 text-sm font-medium text-fg-primary">
+            <span>{t("auth.username")}</span>
+            <input
+              className="input h-11 w-full px-4"
+              autoComplete="username"
+              autoFocus
+              required
+              placeholder={t("auth.username")}
+              value={username}
+              onChange={(e) => setUsername(e.target.value)}
+            />
+          </label>
+          <div className="space-y-1.5 text-sm font-medium text-fg-primary">
+            <label htmlFor="login-password">{t("auth.password")}</label>
+            <div className="relative">
+              <input
+                id="login-password"
+                className="input h-11 w-full pl-4 pr-11"
+                type={showPassword ? "text" : "password"}
+                autoComplete="current-password"
+                required
+                placeholder="••••••••"
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+              />
+              <button
+                type="button"
+                onClick={() => setShowPassword((v) => !v)}
+                aria-label={showPassword ? t("auth.hidePassword") : t("auth.showPassword")}
+                aria-pressed={showPassword}
+                className="absolute inset-y-0 right-0 flex w-11 items-center justify-center rounded-r-lg text-fg-muted hover:text-fg-primary focus:outline-none focus-visible:ring-2 focus-visible:ring-accent"
+              >
+                {showPassword ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
+              </button>
+            </div>
+          </div>
+          {error && (
+            <p role="alert" className="text-sm text-status-danger">
+              {error}
+            </p>
+          )}
+          {/* Inverted fill (text colour behind the surface colour): black in a
+              light theme, light in a dark one, like the reference design. */}
+          <button
+            type="submit"
+            className="h-11 w-full rounded-xl bg-fg-primary text-sm font-medium text-surface-0 shadow-sm transition-opacity hover:opacity-90 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface-0 disabled:cursor-not-allowed disabled:opacity-50"
+            disabled={busy}
+          >
+            {busy ? t("auth.submitting") : t("auth.submit")}
+          </button>
+          <p className="text-center text-sm text-fg-secondary">{t("auth.noAccount")}</p>
+        </div>
+      </form>
+    </main>
+  );
+}
@@ -74,29 +74,54 @@ export interface CheckboxProps {
  className?: string;
  /** Classes applied to the label `<span>` when `label` is set. */
  labelClassName?: string;
+  /** `danger` / `warning` for an opt-in that makes an action riskier
+   *  (bypass permissions, purge data, force). */
+  tone?: "accent" | "danger" | "warning";
+  disabled?: boolean;
+  /** Tooltip (the app turns every `title` into its themed bubble). */
+  title?: string;
 }

+// Fill + tick per tone. Accent fills with `accent-solid` under a white tick.
+// The status colours are TEXT shades — light in dark mode, dark in light mode —
+// so their tick takes the page colour (surface-0), which contrasts both ways.
+const TONE = {
+  accent: "bg-accent-solid border-accent-solid text-white",
+  danger: "bg-status-danger border-status-danger text-surface-0",
+  warning: "bg-status-warning border-status-warning text-surface-0",
+} as const;
+
 /**
- * Themed checkbox control.
+ * Themed checkbox control — the app's ONE checkbox; never a native
+ * `<input type="checkbox">`, which renders as the browser's white box.
 * @param props See {@link CheckboxProps}.
 */
-export function Checkbox({ checked, onChange, label, className, labelClassName }: CheckboxProps) {
+export function Checkbox({
+  checked,
+  onChange,
+  label,
+  className,
+  labelClassName,
+  tone = "accent",
+  disabled = false,
+  title,
+}: CheckboxProps) {
  return (
    <button
      type="button"
      role="checkbox"
      aria-checked={checked}
+      disabled={disabled}
+      title={title}
      onClick={() => onChange(!checked)}
-      className={`group inline-flex items-center gap-2 text-left ${className ?? ""}`}
+      className={`group inline-flex items-center gap-2 text-left disabled:cursor-not-allowed disabled:opacity-50 focus-visible:outline-none ${className ?? ""}`}
    >
      <span
-        className={`flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-[5px] border transition-colors ${
-          checked
-            ? "bg-accent border-accent"
-            : "bg-surface-2 border-border group-hover:border-border-light"
+        className={`flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-[5px] border transition-colors group-focus-visible:ring-2 group-focus-visible:ring-accent/60 ${
+          checked ? TONE[tone] : "bg-surface-2 border-fg-muted group-hover:border-fg-secondary"
        }`}
      >
-        {checked && <Check className="h-3 w-3 text-white" strokeWidth={3} />}
+        {checked && <Check className="h-3 w-3" strokeWidth={3} aria-hidden />}
      </span>
      {label != null && (
        <span
@@ -0,0 +1,33 @@
+/**
+ * @file ConfirmHost.tsx
+ * @description Renders the one pending `confirmDialog()` from `lib/confirm.ts`
+ * through `ConfirmModal`. Mounted once in `App.tsx`.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { ConfirmModal } from "./ConfirmModal";
+import { settleConfirm, subscribeConfirm, type PendingConfirm } from "../lib/confirm";
+
+const cancel = () => settleConfirm(false);
+const confirm = () => settleConfirm(true);
+
+/** The single host for `confirmDialog()`. */
+export function ConfirmHost() {
+  const { t } = useTranslation("common");
+  const [p, setP] = useState<PendingConfirm | null>(null);
+  useEffect(() => subscribeConfirm(setP), []);
+  return (
+    <ConfirmModal
+      open={p !== null}
+      title={p?.title ?? ""}
+      message={p?.message}
+      confirmLabel={p?.confirmLabel ?? t("confirm")}
+      cancelLabel={p?.cancelLabel ?? t("cancel")}
+      destructive={p?.destructive ?? true}
+      onConfirm={confirm}
+      onCancel={cancel}
+    />
+  );
+}
@@ -11,12 +11,14 @@
 *
 * ## Accessibility
 * Focus moves to Cancel on open (safer default), Tab cycles within the dialog,
- * Escape cancels, and focus restores to the previously focused element on close.
+ * Escape cancels, and focus restores to the previously focused element on close
+ * (the shared `hooks/useDialog.ts` contract).
 *
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

-import { useEffect, useId, useRef, type ReactNode } from "react";
+import { useId, useRef, type ReactNode } from "react";
+import { useDialog } from "../hooks/useDialog";
 import { AlertTriangle, X } from "lucide-react";

 /** Props for {@link ConfirmModal}. */
@@ -71,70 +73,29 @@ export function ConfirmModal({
  const messageId = useId();
  const panelRef = useRef<HTMLDivElement>(null);
  const cancelRef = useRef<HTMLButtonElement>(null);
-  const previouslyFocused = useRef<HTMLElement | null>(null);
-
-  useEffect(() => {
-    if (!open) return;
-
-    previouslyFocused.current =
-      document.activeElement instanceof HTMLElement ? document.activeElement : null;
-    // Prefer Cancel so Enter/activation doesn't immediately destroy data.
-    const focusTimer = window.setTimeout(() => cancelRef.current?.focus(), 0);
-
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") {
-        e.preventDefault();
-        onCancel();
-        return;
-      }
-      if (e.key !== "Tab" || !panelRef.current) return;
-
-      const focusable = panelRef.current.querySelectorAll<HTMLElement>(
-        'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
-      );
-      if (focusable.length === 0) return;
-      const first = focusable.item(0);
-      const last = focusable.item(focusable.length - 1);
-      if (!first || !last) return;
-      if (e.shiftKey && document.activeElement === first) {
-        e.preventDefault();
-        last.focus();
-      } else if (!e.shiftKey && document.activeElement === last) {
-        e.preventDefault();
-        first.focus();
-      }
-    };
-
-    document.addEventListener("keydown", onKey);
-    return () => {
-      window.clearTimeout(focusTimer);
-      document.removeEventListener("keydown", onKey);
-      previouslyFocused.current?.focus?.();
-      previouslyFocused.current = null;
-    };
-  }, [open, onCancel]);
+  useDialog(open, panelRef, onCancel, cancelRef);

  if (!open) return null;

  return (
    <div
-      className="fixed inset-0 bg-black/60 z-50 flex items-center justify-center p-4"
+      className="fixed inset-0 bg-black/60 z-[60] flex items-center justify-center p-4"
      onClick={onCancel}
      role="presentation"
    >
      <div
        ref={panelRef}
-        className="relative w-full max-w-md rounded-xl border border-border bg-surface-1 shadow-xl shadow-black/40"
+        className="relative flex max-h-full w-full max-w-md flex-col rounded-xl border border-border bg-surface-1 shadow-xl shadow-black/40"
        onClick={(e) => e.stopPropagation()}
        role="dialog"
        aria-modal="true"
        aria-labelledby={titleId}
        aria-describedby={message ? messageId : undefined}
      >
-        <div className="flex items-start gap-3 p-5">
+        <div className="flex min-h-0 items-start gap-3 overflow-y-auto p-5">
          {destructive && (
            <div className="w-9 h-9 rounded-lg bg-status-danger/10 border border-status-danger/20 flex items-center justify-center flex-shrink-0">
-              <AlertTriangle className="w-4.5 h-4.5 text-status-danger" />
+              <AlertTriangle className="w-4.5 h-4.5 text-status-danger" aria-hidden />
            </div>
          )}
          <div className="min-w-0 flex-1">
@@ -151,10 +112,10 @@ export function ConfirmModal({
          <button
            type="button"
            onClick={onCancel}
-            className="text-fg-muted hover:text-fg-secondary p-1 -mt-1 -mr-1"
+            className="btn-icon -mt-1 -mr-1"
            aria-label={cancelLabel}
          >
-            <X className="w-4 h-4" />
+            <X className="w-4 h-4" aria-hidden />
          </button>
        </div>
        <div className="flex items-center justify-end gap-2 px-5 pb-5">
@@ -0,0 +1,192 @@
+/**
+ * @file ContextMenu — the one shell every right-click (and `⋯`) menu opens
+ * in: a fixed list at a viewport point, rendered into `document.body` so no
+ * transformed or clipped ancestor moves it, nudged back inside the viewport
+ * once measured, closed by Escape, a press outside it, or after an item runs.
+ * `useContextMenu` keeps "which item, where" for a list of rows; `menuPoint`
+ * turns a mouse event into that point (and stops the browser's own menu).
+ *
+ * Keyboard (WAI-ARIA menu): the first enabled item takes focus on open;
+ * Up/Down wrap, Home/End jump, Escape and Tab close, and focus goes back to
+ * what held it before the menu opened — unless an item moved it elsewhere
+ * (a rename field, a dialog). A menu opened from the keyboard (Shift+F10 or
+ * the Menu key reports clientX/Y 0) anchors under the element instead of the
+ * viewport's corner.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import type { KeyboardEvent as ReactKeyboardEvent, MouseEvent as ReactMouseEvent } from "react";
+
+export type MenuPoint = { x: number; y: number };
+
+/** The pointer of a right-click, the browser's own menu suppressed. A
+ *  keyboard-opened menu has no pointer, so it anchors under the element. */
+export function menuPoint(e: ReactMouseEvent): MenuPoint {
+  e.preventDefault();
+  e.stopPropagation();
+  if (e.clientX === 0 && e.clientY === 0 && e.currentTarget instanceof Element) {
+    const r = e.currentTarget.getBoundingClientRect();
+    return { x: r.left, y: r.bottom };
+  }
+  return { x: e.clientX, y: e.clientY };
+}
+
+/** Menu state for a list of rows: which row's menu is open, and where. */
+export function useContextMenu<T>() {
+  const [menu, setMenu] = useState<(MenuPoint & { item: T }) | null>(null);
+  const open = useCallback((e: ReactMouseEvent, item: T) => {
+    setMenu({ ...menuPoint(e), item });
+  }, []);
+  const close = useCallback(() => setMenu(null), []);
+  return { menu, open, close };
+}
+
+const MARGIN = 8;
+const stop = (e: { stopPropagation: () => void }) => e.stopPropagation();
+const ITEMS = '[role="menuitem"]:not([disabled]):not([aria-disabled="true"])';
+
+export function ContextMenu({
+  x,
+  y,
+  onClose,
+  testId,
+  className = "w-56",
+  children,
+}: MenuPoint & {
+  onClose: () => void;
+  testId?: string;
+  className?: string;
+  children: ReactNode;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [pos, setPos] = useState({ left: x, top: y });
+
+  // Focus in on open, back out on close. Runs once per mount: a menu that
+  // moves to a new point keeps its focus.
+  useEffect(() => {
+    const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    ref.current?.querySelector<HTMLElement>(ITEMS)?.focus({ preventScroll: true });
+    return () => {
+      // Only when focus would otherwise be lost (it sat on a removed item).
+      const now = document.activeElement;
+      if (!now || now === document.body || ref.current?.contains(now)) previous?.focus?.();
+    };
+  }, []);
+
+  const onKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    const inField = (e.target as HTMLElement).closest(
+      "input, textarea, select, [contenteditable='true']"
+    );
+    if (e.key === "Escape" || (e.key === "Tab" && !inField)) {
+      // Handled here so a dialog behind the menu does not close as well.
+      e.preventDefault();
+      e.stopPropagation();
+      onClose();
+      return;
+    }
+    // A field inside a menu (a size slider, a search box) keeps its own keys.
+    if (inField) return;
+    const items = [...(ref.current?.querySelectorAll<HTMLElement>(ITEMS) ?? [])];
+    if (items.length === 0) return;
+    const i = items.indexOf(document.activeElement as HTMLElement);
+    const next =
+      e.key === "ArrowDown"
+        ? (i + 1) % items.length
+        : e.key === "ArrowUp"
+          ? (i - 1 + items.length) % items.length
+          : e.key === "Home"
+            ? 0
+            : e.key === "End"
+              ? items.length - 1
+              : -1;
+    if (next < 0) return;
+    e.preventDefault();
+    items[next]!.focus();
+  };
+
+  useLayoutEffect(() => {
+    const r = ref.current?.getBoundingClientRect();
+    if (!r) return;
+    setPos({
+      left: Math.max(MARGIN, Math.min(x, window.innerWidth - r.width - MARGIN)),
+      top: Math.max(MARGIN, Math.min(y, window.innerHeight - r.height - MARGIN)),
+    });
+  }, [x, y]);
+
+  useEffect(() => {
+    const onDown = (e: MouseEvent) => {
+      if (!ref.current?.contains(e.target as Node)) onClose();
+    };
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
+    document.addEventListener("mousedown", onDown);
+    document.addEventListener("keydown", onKey);
+    window.addEventListener("blur", onClose);
+    window.addEventListener("resize", onClose);
+    return () => {
+      document.removeEventListener("mousedown", onDown);
+      document.removeEventListener("keydown", onKey);
+      window.removeEventListener("blur", onClose);
+      window.removeEventListener("resize", onClose);
+    };
+  }, [onClose]);
+
+  return createPortal(
+    <div
+      ref={ref}
+      role="menu"
+      data-testid={testId}
+      style={pos}
+      // A portal still bubbles React events to the component that rendered
+      // it — a menu opened from a clickable card must not click the card too.
+      onClick={stop}
+      onDoubleClick={stop}
+      onMouseDown={stop}
+      onPointerDown={stop}
+      onKeyDown={onKeyDown}
+      onContextMenu={(e) => {
+        e.preventDefault();
+        e.stopPropagation();
+      }}
+      className={`fixed z-50 rounded-lg border border-border bg-surface-2 p-1 shadow-lg ${className}`}
+    >
+      {children}
+    </div>,
+    document.body
+  );
+}
+
+export const MENU_ITEM =
+  "flex w-full items-center gap-2 rounded px-2 py-1 text-left text-xs text-fg-secondary hover:bg-surface-4 hover:text-fg-primary focus:outline-none focus-visible:bg-surface-4 focus-visible:text-fg-primary focus-visible:ring-1 focus-visible:ring-accent/60 disabled:pointer-events-none disabled:opacity-50";
+
+export function MenuItem({
+  onSelect,
+  danger,
+  disabled,
+  testId,
+  children,
+}: {
+  onSelect: () => void;
+  danger?: boolean;
+  disabled?: boolean;
+  testId?: string;
+  children: ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      data-testid={testId}
+      disabled={disabled}
+      className={`${MENU_ITEM}${danger ? " !text-status-danger" : ""}`}
+      onClick={onSelect}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function MenuSeparator() {
+  return <div role="separator" className="my-1 border-t border-border" />;
+}
@@ -43,6 +43,7 @@
 * ----------------------------------------------------------------------------- */

 import React, { useState, useRef, useEffect } from "react";
+import { useTranslation } from "react-i18next";
 import { Calendar, Clock, ChevronLeft, ChevronRight, X } from "lucide-react";

 interface DateTimePickerProps {
@@ -52,16 +53,22 @@ interface DateTimePickerProps {
  className?: string;
  "aria-label"?: string;
  title?: string;
+  /** A "to" bound: picking a day with no time yet means the END of that day
+   *  (23:59), not its first minute. */
+  endOfDay?: boolean;
 }

 export function DateTimePicker({
  value,
  onChange,
-  placeholder = "Select date & time",
+  placeholder,
  className = "",
  "aria-label": ariaLabel,
  title,
+  endOfDay = false,
 }: DateTimePickerProps) {
+  const { t, i18n } = useTranslation("sessions");
+  const locale = i18n.resolvedLanguage ?? i18n.language;
  const [isOpen, setIsOpen] = useState(false);
  const [alignment, setAlignment] = useState<"left" | "right">("left");
  const containerRef = useRef<HTMLDivElement>(null);
@@ -97,9 +104,18 @@ export function DateTimePicker({
    return () => document.removeEventListener("mousedown", handleClickOutside);
  }, []);

+  useEffect(() => {
+    if (!isOpen) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setIsOpen(false);
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [isOpen]);
+
  const formatDisplay = (d: Date | null) => {
    if (!d || isNaN(d.getTime())) return "";
-    return d.toLocaleString(undefined, {
+    return d.toLocaleString(locale, {
      month: "short",
      day: "numeric",
      hour: "2-digit",
@@ -112,7 +128,9 @@ export function DateTimePicker({
    if (dateObj && !isNaN(dateObj.getTime())) {
      newDate.setHours(dateObj.getHours(), dateObj.getMinutes());
    } else {
-      newDate.setHours(0, 0); // Default midnight
+      // Default: midnight, or 23:59 for an end bound so the day is included.
+      if (endOfDay) newDate.setHours(23, 59, 59, 999);
+      else newDate.setHours(0, 0);
    }
    updateValue(newDate);
  };
@@ -135,7 +153,9 @@ export function DateTimePicker({
    const day = String(d.getDate()).padStart(2, "0");
    const h = String(d.getHours()).padStart(2, "0");
    const mi = String(d.getMinutes()).padStart(2, "0");
-    onChange(`${y}-${mo}-${day}T${h}:${mi}`);
+    // An end bound carries its :59.999 so the whole last minute is included.
+    const tail = endOfDay ? ":59.999" : "";
+    onChange(`${y}-${mo}-${day}T${h}:${mi}${tail}`);
  };

  const clearValue = (e: React.MouseEvent) => {
@@ -168,13 +188,18 @@ export function DateTimePicker({
        key={i}
        type="button"
        onClick={() => handleDateClick(i)}
+        aria-label={new Date(viewDate.getFullYear(), viewDate.getMonth(), i).toLocaleDateString(
+          locale,
+          { weekday: "long", year: "numeric", month: "long", day: "numeric" }
+        )}
+        aria-pressed={isSelected}
        className={`w-6 h-6 flex items-center justify-center rounded text-[11px] transition-colors
          ${
            isSelected
-              ? "bg-accent text-white font-medium"
+              ? "bg-accent-solid text-white font-medium"
              : isToday
                ? "bg-surface-3 text-accent font-medium"
-                : "hover:bg-surface-2 text-fg-secondary hover:text-white"
+                : "hover:bg-surface-2 text-fg-secondary hover:text-fg-primary"
          }`}
      >
        {i}
@@ -193,17 +218,27 @@ export function DateTimePicker({
        type="button"
        onClick={() => setIsOpen(!isOpen)}
        aria-label={ariaLabel}
+        aria-expanded={isOpen}
+        aria-haspopup="dialog"
        title={title}
-        className={`flex items-center gap-2 bg-surface-2 border ${isOpen ? "border-accent" : "border-border"} rounded px-2 py-1.5 min-w-[150px] text-xs focus:outline-none focus:border-accent transition-colors w-full text-left`}
+        className={`flex items-center gap-2 bg-surface-2 border ${isOpen ? "border-accent" : "border-border"} rounded px-2 py-1.5 min-w-[150px] text-xs focus:outline-none focus:border-accent transition-colors w-full text-left ${dateObj ? "pr-7" : ""}`}
      >
        <Calendar className="w-3.5 h-3.5 text-fg-secondary shrink-0" />
        <span className={`flex-1 truncate ${!dateObj ? "text-fg-muted" : "text-fg-secondary"}`}>
-          {dateObj ? formatDisplay(dateObj) : placeholder}
+          {dateObj ? formatDisplay(dateObj) : (placeholder ?? t("datePicker.placeholder"))}
        </span>
-        {dateObj && (
-          <X className="w-3 h-3 text-fg-muted hover:text-white shrink-0" onClick={clearValue} />
-        )}
      </button>
+      {/* A sibling, not a child: a button inside a button is not reachable by keyboard. */}
+      {dateObj && (
+        <button
+          type="button"
+          onClick={clearValue}
+          aria-label={t("datePicker.clear")}
+          className="absolute right-1.5 top-1/2 -translate-y-1/2 p-0.5 rounded text-fg-muted hover:text-fg-primary"
+        >
+          <X className="w-3 h-3" />
+        </button>
+      )}

      {isOpen && (
        <div
@@ -216,19 +251,21 @@ export function DateTimePicker({
              onClick={() =>
                setViewDate(new Date(viewDate.getFullYear(), viewDate.getMonth() - 1, 1))
              }
-              className="p-1 hover:bg-surface-2 rounded text-fg-secondary hover:text-white"
+              aria-label={t("datePicker.prevMonth")}
+              className="p-1 hover:bg-surface-2 rounded text-fg-secondary hover:text-fg-primary"
            >
              <ChevronLeft className="w-4 h-4" />
            </button>
            <span className="text-xs font-medium text-fg-secondary">
-              {viewDate.toLocaleString(undefined, { month: "long", year: "numeric" })}
+              {viewDate.toLocaleString(locale, { month: "long", year: "numeric" })}
            </span>
            <button
              type="button"
              onClick={() =>
                setViewDate(new Date(viewDate.getFullYear(), viewDate.getMonth() + 1, 1))
              }
-              className="p-1 hover:bg-surface-2 rounded text-fg-secondary hover:text-white"
+              aria-label={t("datePicker.nextMonth")}
+              className="p-1 hover:bg-surface-2 rounded text-fg-secondary hover:text-fg-primary"
            >
              <ChevronRight className="w-4 h-4" />
            </button>
@@ -237,8 +274,15 @@ export function DateTimePicker({
          {/* Calendar Grid */}
          <div>
            <div className="grid grid-cols-7 gap-1 mb-1">
-              {["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"].map((day) => (
-                <div key={day} className="w-6 text-center text-[10px] font-medium text-fg-muted">
+              {/* 2026-01-04 is a Sunday: seven local days give the weekday initials. */}
+              {Array.from({ length: 7 }, (_, d) =>
+                new Date(2026, 0, 4 + d).toLocaleDateString(locale, { weekday: "narrow" })
+              ).map((day, d) => (
+                <div
+                  key={d}
+                  aria-hidden
+                  className="w-6 text-center text-[10px] font-medium text-fg-muted"
+                >
                  {day}
                </div>
              ))}
@@ -250,10 +294,11 @@ export function DateTimePicker({
          <div className="pt-3 border-t border-border flex items-center justify-between">
            <div className="flex items-center gap-1.5 text-fg-secondary">
              <Clock className="w-3.5 h-3.5" />
-              <span className="text-[11px] font-medium">Time</span>
+              <span className="text-[11px] font-medium">{t("datePicker.time")}</span>
            </div>
            <input
              type="time"
+              aria-label={t("datePicker.time")}
              value={timeValue}
              onChange={handleTimeChange}
              className="bg-surface-2 border border-border rounded px-2 py-1 text-xs text-fg-secondary focus:outline-none focus:border-accent w-[85px] time-input-custom"
@@ -24,8 +24,6 @@ export function DocumentTitle() {
    title = `${t("sessions")} · ${sessionId.slice(0, 8)}`;
  } else if (path.startsWith("/sessions")) {
    title = t("sessions");
-  } else if (path.startsWith("/workflows")) {
-    title = t("workflows");
  } else if (path.startsWith("/workspace")) {
    title = t("workspace");
  } else if (path.startsWith("/settings")) {
@@ -75,20 +75,26 @@ export interface EmptyStateProps {
  description: string;
  /** Optional CTA rendered below the description (button, link, or form). */
  action?: React.ReactNode;
+  /** Inside a card (a settings panel) rather than a whole page: less padding. */
+  compact?: boolean;
 }

 /**
 * Renders a vertically centered empty state inside the main content column.
 * @param props See {@link EmptyStateProps}.
 */
-export function EmptyState({ icon: Icon, title, description, action }: EmptyStateProps) {
+export function EmptyState({ icon: Icon, title, description, action, compact }: EmptyStateProps) {
  return (
-    <div className="flex flex-col items-center justify-center py-20 text-center">
-      <div className="w-14 h-14 rounded-2xl bg-surface-4 flex items-center justify-center mb-5">
-        <Icon className="w-6 h-6 text-fg-muted" />
+    <div
+      className={`flex flex-col items-center justify-center text-center ${compact ? "py-8" : "py-20"}`}
+    >
+      <div
+        className={`rounded-2xl bg-surface-4 flex items-center justify-center ${compact ? "w-10 h-10 mb-3" : "w-14 h-14 mb-5"}`}
+      >
+        <Icon className="w-6 h-6 text-fg-muted" aria-hidden />
      </div>
      <h3 className="text-base font-medium text-fg-secondary mb-2">{title}</h3>
-      <p className="text-sm text-fg-muted max-w-md mb-6">{description}</p>
+      <p className={`text-sm text-fg-muted max-w-md ${compact ? "" : "mb-6"}`}>{description}</p>
      {action}
    </div>
  );
@@ -277,7 +277,7 @@ function SummaryBlock({
    refs.length > 0 ? t("eventDetail.seeDetailsBelow", { fields: refs.join(" · ") }) : null;
  return (
    <div className="border border-border rounded overflow-hidden bg-surface-3/30">
-      <div className="px-3 py-1 border-b border-border bg-black/20">
+      <div className="px-3 py-1 border-b border-border bg-surface-1">
        <span className="text-fg-muted text-[10px] uppercase tracking-wide font-semibold">
          {t("eventDetail.summary")}
        </span>
@@ -379,7 +379,7 @@ function ScalarValue({ value }: { value: unknown }) {
  if (value == null) return <span className="text-fg-muted italic">null</span>;
  if (typeof value === "boolean") {
    const color = value
-      ? "text-green-400 border-green-500/30 bg-green-500/10"
+      ? "text-green-700 dark:text-green-400 border-green-500/30 bg-green-500/10"
      : "text-fg-secondary border-border-light/30 bg-surface-4/10";
    return (
      <span className={`inline-block px-2 py-0.5 rounded border ${color}`}>{String(value)}</span>
@@ -394,8 +394,8 @@ function CodeView({ value }: { value: unknown }) {
  const text = typeof value === "string" ? value : safeStringify(value);

  return (
-    <div className="relative bg-black/70 border border-border rounded font-mono text-[11px] overflow-hidden">
-      <div className="flex items-center justify-between px-3 py-1.5 border-b border-border bg-black/40">
+    <div className="relative bg-surface-0 border border-border rounded font-mono text-[11px] overflow-hidden">
+      <div className="flex items-center justify-between px-3 py-1.5 border-b border-border bg-surface-1">
        <span className="text-fg-muted text-[10px] uppercase tracking-wide">
          {typeof value === "string" ? "text" : Array.isArray(value) ? "array" : "json"}
        </span>
@@ -86,7 +86,8 @@
 *
 * ----------------------------------------------------------------------------- */

-import { useEffect, useRef, useState } from "react";
+import { Checkbox } from "./Checkbox";
+import React, { useEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { Search, X, Filter } from "lucide-react";
 import { api } from "../lib/api";
@@ -114,6 +115,45 @@ export const EMPTY_FILTERS: EventFiltersValue = {
  to: "",
 };

+/** URL key per filter field (short, so a shared link stays readable). */
+const PARAM_OF: Record<keyof EventFiltersValue, string> = {
+  event_type: "et",
+  tool_name: "tn",
+  agent_id: "ag",
+  session_id: "sid",
+  status: "st",
+  q: "q",
+  from: "from",
+  to: "to",
+};
+
+/** Filters read from the URL (lists are comma-joined). */
+export function filtersFromParams(params: URLSearchParams): EventFiltersValue {
+  const list = (k: string) => (params.get(k) ?? "").split(",").filter(Boolean);
+  return {
+    event_type: list(PARAM_OF.event_type),
+    tool_name: list(PARAM_OF.tool_name),
+    agent_id: list(PARAM_OF.agent_id),
+    session_id: list(PARAM_OF.session_id),
+    status: list(PARAM_OF.status),
+    q: params.get(PARAM_OF.q) ?? "",
+    from: params.get(PARAM_OF.from) ?? "",
+    to: params.get(PARAM_OF.to) ?? "",
+  };
+}
+
+/** A copy of `base` with the filter keys rewritten; empty filters are dropped. */
+export function filtersToParams(f: EventFiltersValue, base: URLSearchParams): URLSearchParams {
+  const next = new URLSearchParams(base);
+  for (const [field, key] of Object.entries(PARAM_OF) as [keyof EventFiltersValue, string][]) {
+    const v = f[field];
+    const str = Array.isArray(v) ? v.join(",") : v;
+    if (str) next.set(key, str);
+    else next.delete(key);
+  }
+  return next;
+}
+
 export function isEmptyFilters(f: EventFiltersValue): boolean {
  return (
    f.event_type.length === 0 &&
@@ -179,13 +219,18 @@ export function EventFilters({
    tool_names: [],
  });
  const [searchDraft, setSearchDraft] = useState(value.q);
+  // The debounced search merges into the LATEST value: a chip toggled during
+  // the 300 ms must not be reverted by the value captured at keystroke time.
+  const valueRef = useRef(value);
+  valueRef.current = value;

  // Debounce text search - only push up after 300ms of inactivity.
  const searchTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
  useEffect(() => {
    if (searchTimer.current) clearTimeout(searchTimer.current);
    searchTimer.current = setTimeout(() => {
-      if (searchDraft !== value.q) onChange({ ...value, q: searchDraft });
+      const latest = valueRef.current;
+      if (searchDraft !== latest.q) onChange({ ...latest, q: searchDraft });
    }, 300);
    return () => {
      if (searchTimer.current) clearTimeout(searchTimer.current);
@@ -247,6 +292,7 @@ export function EventFilters({
        />
        <span className="text-xs text-fg-muted">→</span>
        <DateTimePicker
+          endOfDay
          value={value.to}
          onChange={(val: string) => onChange({ ...value, to: val })}
          aria-label={t("eventFilters.to")}
@@ -300,11 +346,10 @@ export function EventFilters({
            onToggle={(item) => toggle("agent_id", item)}
          />
        )}
-        {!hideSessionFilter && sessionOptions && sessionOptions.length > 0 && (
-          <ChipGroup
+        {!hideSessionFilter && (
+          <SessionChipGroup
            label={t("eventFilters.sessionId")}
-            options={sessionOptions.map((s) => s.id)}
-            labels={Object.fromEntries(sessionOptions.map((s) => [s.id, s.label]))}
+            known={sessionOptions}
            selected={value.session_id}
            onToggle={(item) => toggle("session_id", item)}
          />
@@ -314,22 +359,98 @@ export function EventFilters({
  );
 }

+/**
+ * The session filter: searched on the server (`q`, 20 rows), never a list of
+ * every session. Selected ids stay listed (with the label last seen) so they
+ * can be unticked while the search shows other rows.
+ */
+function SessionChipGroup({
+  label,
+  known,
+  selected,
+  onToggle,
+}: {
+  label: string;
+  known?: Array<{ id: string; label: string }>;
+  selected: string[];
+  onToggle: (item: string) => void;
+}) {
+  const { t } = useTranslation("common");
+  const [query, setQuery] = useState("");
+  const [rows, setRows] = useState<Array<{ id: string; label: string }>>([]);
+  const labels = useRef(new Map<string, string>());
+  for (const k of known ?? []) labels.current.set(k.id, k.label);
+  const [open, setOpen] = useState(false);
+  const seq = useRef(0);
+
+  useEffect(() => {
+    if (!open) return;
+    const timer = setTimeout(
+      () => {
+        const mine = ++seq.current;
+        api.sessions
+          .list({ q: query.trim() || undefined, limit: 20 })
+          .then((res) => {
+            if (mine !== seq.current) return;
+            const next = res.sessions.map((s) => ({
+              id: s.id,
+              label: s.name?.trim() || s.id.slice(0, 8),
+            }));
+            for (const r of next) labels.current.set(r.id, r.label);
+            setRows(next);
+          })
+          .catch(() => undefined);
+      },
+      query ? 250 : 0
+    );
+    return () => clearTimeout(timer);
+  }, [open, query]);
+
+  const options = [...selected, ...rows.map((r) => r.id).filter((id) => !selected.includes(id))];
+  return (
+    <ChipGroup
+      label={label}
+      options={options}
+      labels={Object.fromEntries(options.map((id) => [id, labels.current.get(id) ?? id]))}
+      selected={selected}
+      onToggle={onToggle}
+      onOpenChange={setOpen}
+      search={
+        <input
+          type="search"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder={t("eventFilters.searchPlaceholder")}
+          aria-label={label}
+          className="w-full mb-1 bg-surface-2 border border-border rounded px-2 py-1 text-[11px] text-fg-secondary focus:outline-none focus:border-accent"
+        />
+      }
+    />
+  );
+}
+
 function ChipGroup({
  label,
  options,
  selected,
  onToggle,
  labels,
+  onOpenChange,
+  search,
 }: {
  label: string;
  options: string[];
  selected: string[];
  onToggle: (item: string) => void;
  labels?: Record<string, string>;
+  onOpenChange?: (open: boolean) => void;
+  /** Rendered above the options (a search box). */
+  search?: React.ReactNode;
 }) {
  const { t } = useTranslation("common");
  const [open, setOpen] = useState(false);
  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => onOpenChange?.(open), [open, onOpenChange]);

  // Click-outside dismiss.
  useEffect(() => {
@@ -367,6 +488,7 @@ function ChipGroup({
          aria-label={label}
          className="absolute left-0 mt-1 z-20 min-w-[220px] max-h-64 overflow-auto bg-surface-1 border border-border rounded shadow-xl p-1.5"
        >
+          {search}
          {options.length === 0 ? (
            <p className="text-[11px] text-fg-muted px-2 py-1 italic">
              {t("eventFilters.noOptions")}
@@ -376,18 +498,14 @@ function ChipGroup({
              const checked = selected.includes(opt);
              const display = labels?.[opt] ?? opt;
              return (
-                <label
+                <Checkbox
                  key={opt}
-                  className="flex items-center gap-2 px-2 py-1 text-[11px] text-fg-secondary rounded hover:bg-surface-3 cursor-pointer"
-                >
-                  <input
-                    type="checkbox"
-                    checked={checked}
-                    onChange={() => onToggle(opt)}
-                    className="accent-accent"
-                  />
-                  <span className="font-mono break-all">{display}</span>
-                </label>
+                  checked={checked}
+                  onChange={() => onToggle(opt)}
+                  label={display}
+                  className="flex w-full px-2 py-1 rounded hover:bg-surface-3"
+                  labelClassName="font-mono break-all text-[11px] text-fg-secondary"
+                />
              );
            })
          )}
@@ -100,7 +100,7 @@ export function EventFiltersInfo() {
          <p className="text-[11px] text-fg-secondary mb-2">
            {t("eventFilters.help.lifecycleDesc")}
          </p>
-          <code className="block bg-black/40 border border-border rounded p-2 text-[11px] font-mono text-fg-secondary whitespace-pre-wrap">
+          <code className="block bg-surface-1 border border-border rounded p-2 text-[11px] font-mono text-fg-secondary whitespace-pre-wrap">
            {t("eventFilters.help.lifecycleFlow")}
          </code>
        </Section>
@@ -0,0 +1,289 @@
+/**
+ * @file EventReplay.tsx
+ * @description The session Replay tab: a scrubber over a session's recorded
+ * events (play/pause, 0.5×–5×, step, jump, arrow keys), a lifecycle mini-map
+ * whose markers jump the cursor, the state derived up to the cursor
+ * (`lib/replay.ts`) and the selected event through EventDetail. Fed a list of
+ * events, so the live analysis page and a frozen snapshot share it.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useMemo, useState, type KeyboardEvent, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { Pause, Play, SkipBack, SkipForward, StepBack, StepForward } from "lucide-react";
+import { api } from "../lib/api";
+import {
+  chronological,
+  lifecycleMarkers,
+  replayState,
+  LIFECYCLE_TYPES,
+  REPLAY_SPEEDS,
+  REPLAY_STEP_MS,
+} from "../lib/replay";
+import { buildEventTitle } from "../lib/event-grouping";
+import type { AgentInfo } from "../lib/event-grouping";
+import { formatDateTimeFull, formatMs } from "../lib/format";
+import type { DashboardEvent } from "../lib/types";
+import { AgentStatusBadge } from "./StatusBadge";
+import { EventDetail } from "./EventDetail";
+
+/** The newest this many events are replayed; older ones are left out. */
+export const REPLAY_MAX_EVENTS = 5000;
+const PAGE = 500;
+
+/** A session's events in playback order (the newest REPLAY_MAX_EVENTS). */
+export async function loadReplayEvents(
+  sessionId: string
+): Promise<{ events: DashboardEvent[]; total: number }> {
+  const all: DashboardEvent[] = [];
+  let total = 0;
+  do {
+    const r = await api.events.list({ session_id: sessionId, limit: PAGE, offset: all.length });
+    total = r.total;
+    if (r.events.length === 0) break;
+    all.push(...r.events);
+  } while (all.length < Math.min(total, REPLAY_MAX_EVENTS));
+  return { events: chronological(all.slice(0, REPLAY_MAX_EVENTS)), total };
+}
+
+const MARKER_COLOR: Record<string, string> = {
+  SessionStart: "bg-status-success",
+  UserPromptSubmit: "bg-accent",
+  Compaction: "bg-status-warning",
+  SubagentStop: "bg-violet-500",
+  APIError: "bg-status-danger",
+  Stop: "bg-fg-muted",
+};
+
+const btn =
+  "inline-flex h-8 w-8 items-center justify-center rounded-md text-fg-secondary hover:bg-surface-3 hover:text-fg-primary disabled:opacity-40 disabled:cursor-not-allowed";
+
+export function EventReplay({
+  events: raw,
+  total,
+  agentInfoById,
+  sessionNameById,
+}: {
+  events: DashboardEvent[];
+  /** The session's full event count, when more than `events` were recorded. */
+  total?: number;
+  agentInfoById: Map<string, AgentInfo>;
+  sessionNameById: Map<string, string>;
+}) {
+  const { t } = useTranslation("sessions");
+  const events = useMemo(() => chronological(raw), [raw]);
+  const markers = useMemo(() => lifecycleMarkers(events), [events]);
+  const last = events.length - 1;
+  const [cursor, setCursor] = useState(0);
+  const [playing, setPlaying] = useState(false);
+  const [speed, setSpeed] = useState<number>(1);
+  const at = Math.min(cursor, Math.max(0, last));
+  const state = useMemo(() => replayState(events, at), [events, at]);
+  const event = events[at];
+
+  useEffect(() => {
+    if (!playing) return;
+    if (at >= last) {
+      setPlaying(false);
+      return;
+    }
+    const timer = setTimeout(() => setCursor((c) => Math.min(c + 1, last)), REPLAY_STEP_MS / speed);
+    return () => clearTimeout(timer);
+  }, [playing, at, last, speed]);
+
+  if (!event) return <p className="text-sm text-fg-muted">{t("detail.noEvents")}</p>;
+
+  const go = (i: number) => setCursor(Math.max(0, Math.min(last, i)));
+  const toggle = () => {
+    if (!playing && at >= last) setCursor(0);
+    setPlaying((p) => !p);
+  };
+  const onKey = (e: KeyboardEvent) => {
+    // The slider steps itself on arrow keys; only the rest is ours there.
+    const onSlider = e.target instanceof HTMLInputElement;
+    if (e.key === " " && !(e.target instanceof HTMLButtonElement)) {
+      e.preventDefault();
+      toggle();
+    } else if (onSlider) return;
+    else if (e.key === "ArrowLeft") go(at - 1);
+    else if (e.key === "ArrowRight") go(at + 1);
+    else if (e.key === "Home") go(0);
+    else if (e.key === "End") go(last);
+    else return;
+    e.preventDefault();
+  };
+  const markerLabel = (type: string) => t(`replay.marker.${type}`);
+  const present = LIFECYCLE_TYPES.filter((k) => markers.some((m) => m.type === k));
+
+  return (
+    <div
+      className="space-y-4 outline-none"
+      tabIndex={0}
+      onKeyDown={onKey}
+      role="group"
+      aria-label={t("replay.label")}
+      data-testid="event-replay"
+    >
+      {total != null && total > events.length && (
+        <p className="text-xs text-fg-muted">
+          {t("replay.truncated", { shown: events.length, total })}
+        </p>
+      )}
+
+      <div className="card space-y-3 p-4">
+        <div className="flex flex-wrap items-center gap-1">
+          <button type="button" className={btn} onClick={() => go(0)} title={t("replay.start")}>
+            <SkipBack className="h-4 w-4" />
+          </button>
+          <button
+            type="button"
+            className={btn}
+            onClick={() => go(at - 1)}
+            disabled={at <= 0}
+            title={t("replay.back")}
+          >
+            <StepBack className="h-4 w-4" />
+          </button>
+          <button
+            type="button"
+            className={`${btn} bg-accent/15 text-accent`}
+            onClick={toggle}
+            title={playing ? t("replay.pause") : t("replay.play")}
+            aria-pressed={playing}
+          >
+            {playing ? <Pause className="h-4 w-4" /> : <Play className="h-4 w-4" />}
+          </button>
+          <button
+            type="button"
+            className={btn}
+            onClick={() => go(at + 1)}
+            disabled={at >= last}
+            title={t("replay.forward")}
+          >
+            <StepForward className="h-4 w-4" />
+          </button>
+          <button type="button" className={btn} onClick={() => go(last)} title={t("replay.end")}>
+            <SkipForward className="h-4 w-4" />
+          </button>
+          <div
+            className="ml-2 flex items-center gap-0.5"
+            role="group"
+            aria-label={t("replay.speed")}
+          >
+            {REPLAY_SPEEDS.map((s) => (
+              <button
+                key={s}
+                type="button"
+                onClick={() => setSpeed(s)}
+                aria-pressed={speed === s}
+                className={`rounded px-2 py-1 text-xs font-mono ${
+                  speed === s
+                    ? "bg-accent/15 text-accent"
+                    : "text-fg-muted hover:bg-surface-3 hover:text-fg-primary"
+                }`}
+              >
+                {s}×
+              </button>
+            ))}
+          </div>
+          <span className="ml-auto font-mono text-xs text-fg-muted">
+            {t("replay.position", { at: at + 1, n: events.length })} ·{" "}
+            {formatDateTimeFull(event.created_at)}
+          </span>
+        </div>
+
+        <input
+          type="range"
+          min={0}
+          max={last}
+          value={at}
+          onChange={(e) => go(Number(e.target.value))}
+          aria-label={t("replay.scrubber")}
+          className="w-full accent-[rgb(var(--accent))]"
+        />
+
+        <div
+          className="relative h-4 rounded bg-surface-2"
+          role="group"
+          aria-label={t("replay.minimap")}
+        >
+          <div
+            className="pointer-events-none absolute inset-y-0 w-px bg-fg-primary"
+            style={{ left: `${last > 0 ? (at / last) * 100 : 0}%` }}
+          />
+          {markers.map((m) => (
+            <button
+              key={m.index}
+              type="button"
+              onClick={() => go(m.index)}
+              title={`${markerLabel(m.type)} · #${m.index + 1}`}
+              aria-label={`${markerLabel(m.type)} · #${m.index + 1}`}
+              className={`absolute inset-y-0 w-1.5 -translate-x-1/2 rounded-sm opacity-80 hover:opacity-100 ${MARKER_COLOR[m.type]}`}
+              style={{ left: `${m.pct}%` }}
+            />
+          ))}
+        </div>
+        {present.length > 0 && (
+          <div className="flex flex-wrap gap-x-3 gap-y-1 text-[11px] text-fg-muted">
+            {present.map((k) => (
+              <span key={k} className="inline-flex items-center gap-1">
+                <span className={`h-2 w-2 rounded-sm ${MARKER_COLOR[k]}`} />
+                {markerLabel(k)}
+              </span>
+            ))}
+          </div>
+        )}
+      </div>
+
+      <div className="grid grid-cols-2 gap-3 md:grid-cols-6">
+        <Tile label={t("replay.state.status")}>
+          {state.status ? <AgentStatusBadge status={state.status} /> : "-"}
+        </Tile>
+        <Tile label={t("replay.state.tool")}>
+          <span className="font-mono">{state.currentTool ?? "-"}</span>
+        </Tile>
+        <Tile label={t("replay.state.prompts")}>{state.prompts}</Tile>
+        <Tile label={t("replay.state.errors")}>{state.errors}</Tile>
+        <Tile label={t("replay.state.compactions")}>{state.compactions}</Tile>
+        <Tile label={t("replay.state.elapsed")}>{formatMs(state.elapsedMs)}</Tile>
+      </div>
+      {state.toolCounts.length > 0 && (
+        <div
+          className="flex flex-wrap gap-1.5"
+          role="group"
+          aria-label={t("replay.state.toolCounts")}
+        >
+          {state.toolCounts.map((x) => (
+            <span
+              key={x.tool}
+              className="rounded bg-surface-2 px-2 py-0.5 font-mono text-[11px] text-fg-secondary"
+            >
+              {x.tool} ×{x.count}
+            </span>
+          ))}
+        </div>
+      )}
+
+      <div className="card overflow-hidden">
+        <div className="border-b border-border px-5 py-3 text-sm text-fg-secondary">
+          <span className="mr-2 font-mono text-xs text-fg-muted">#{at + 1}</span>
+          {buildEventTitle(event)}
+        </div>
+        <EventDetail
+          event={event}
+          agentInfoById={agentInfoById}
+          sessionNameById={sessionNameById}
+        />
+      </div>
+    </div>
+  );
+}
+
+function Tile({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <div className="rounded-lg border border-border bg-surface-2 px-3 py-2">
+      <div className="text-[10px] uppercase tracking-wider text-fg-muted">{label}</div>
+      <div className="mt-1 text-sm font-semibold text-fg-primary">{children}</div>
+    </div>
+  );
+}
@@ -0,0 +1,135 @@
+/**
+ * @file EventTimeline.tsx
+ * @description A session's events as a flat, expandable list — one row per
+ * event (age, status badge, origin · title, tool), opening into EventDetail.
+ * Used by the session analysis page's Timeline tab and the read-only snapshot
+ * page.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { AgentStatusBadge } from "./StatusBadge";
+import { EventDetail } from "./EventDetail";
+import {
+  agentOriginLabel,
+  buildEventTitle,
+  buildOriginLabel,
+  projectFromCwd,
+  projectFromEvent,
+  statusFromEventType,
+} from "../lib/event-grouping";
+import type { AgentInfo } from "../lib/event-grouping";
+import { timeAgo } from "../lib/format";
+import type { DashboardEvent } from "../lib/types";
+
+export function EventTimeline({
+  events,
+  agentInfoById,
+  sessionNameById,
+  fallbackCwd,
+}: {
+  events: DashboardEvent[];
+  agentInfoById: Map<string, AgentInfo>;
+  sessionNameById: Map<string, string>;
+  /** The session's cwd, for events that carry none of their own. */
+  fallbackCwd?: string | null;
+}) {
+  const { t } = useTranslation("sessions");
+  const [expandedEvents, setExpandedEvents] = useState<Set<number>>(() => new Set());
+
+  function toggleEvent(id: number) {
+    setExpandedEvents((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }
+
+  // Precompute project per event so flat-row rendering doesn't re-parse JSON.
+  const projectByEventId = useMemo(() => {
+    const map = new Map<number, string | null>();
+    for (const e of events) map.set(e.id, projectFromEvent(e));
+    return map;
+  }, [events]);
+
+  return (
+    <div className="card overflow-hidden">
+      <div className="divide-y divide-border max-h-[600px] overflow-y-auto overflow-x-auto">
+        {events.map((event, i) => {
+          const key = event.id ?? i;
+          const isOpen = event.id != null && expandedEvents.has(event.id);
+          return (
+            // Off-screen rows skip layout/paint (a long timeline is not virtualized).
+            <div
+              key={key}
+              style={
+                isOpen
+                  ? undefined
+                  : { contentVisibility: "auto", containIntrinsicSize: "auto 45px" }
+              }
+            >
+              <button
+                type="button"
+                onClick={() => event.id != null && toggleEvent(event.id)}
+                aria-expanded={isOpen}
+                aria-label={
+                  isOpen ? t("common:eventDetail.collapse") : t("common:eventDetail.expand")
+                }
+                className="w-full text-left px-5 py-3 flex items-center gap-4 hover:bg-surface-4 transition-colors min-w-0 cursor-pointer"
+              >
+                <span
+                  className={`text-fg-muted text-[10px] w-3 flex-shrink-0 transition-transform ${isOpen ? "rotate-90" : ""}`}
+                  aria-hidden="true"
+                >
+                  ▶
+                </span>
+                <div className="w-16 text-[11px] text-fg-muted font-mono flex-shrink-0">
+                  {timeAgo(event.created_at)}
+                </div>
+                <AgentStatusBadge status={statusFromEventType(event.event_type)} />
+                {(() => {
+                  // Session is implicit on this page - project is
+                  // still shown so the row identifies the working
+                  // directory when you share / search. Events without
+                  // their own cwd (e.g. TurnDuration) fall back to the
+                  // session's cwd so every row carries the dir prefix.
+                  const project =
+                    projectByEventId.get(event.id) ?? projectFromCwd(fallbackCwd) ?? null;
+                  const origin = buildOriginLabel(
+                    project,
+                    null,
+                    agentOriginLabel(event.agent_id, agentInfoById)
+                  );
+                  return (
+                    <span className="text-sm text-fg-secondary flex-1 truncate">
+                      {origin && (
+                        <span className="text-fg-muted mr-1" title={event.agent_id ?? undefined}>
+                          {origin} ·
+                        </span>
+                      )}
+                      {buildEventTitle(event)}
+                    </span>
+                  );
+                })()}
+                {event.tool_name && (
+                  <span className="text-[11px] px-2 py-0.5 bg-surface-2 rounded text-fg-muted font-mono">
+                    {event.tool_name}
+                  </span>
+                )}
+              </button>
+              {isOpen && (
+                <EventDetail
+                  event={event}
+                  agentInfoById={agentInfoById}
+                  sessionNameById={sessionNameById}
+                />
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
@@ -0,0 +1,44 @@
+/**
+ * @file ImageLightbox.tsx
+ * @description One image shown full size over the whole page; a click or
+ * Escape closes it. Rendered into `document.body`, so no pane, its stacking
+ * layer or a header drawn over a pane can cover it — opened from inside a
+ * pane's Chat view, a `fixed` overlay would otherwise stay in that pane's
+ * layer, under anything stacked above it.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect } from "react";
+import { createPortal } from "react-dom";
+
+export function ImageLightbox({
+  src,
+  alt,
+  onClose,
+}: {
+  src: string;
+  alt: string;
+  onClose: () => void;
+}) {
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [onClose]);
+  return createPortal(
+    <div
+      role="dialog"
+      aria-label={alt}
+      data-testid="image-lightbox"
+      onClick={onClose}
+      className="fixed inset-0 z-[200] flex cursor-zoom-out items-center justify-center bg-black/60 p-8"
+    >
+      <img
+        src={src}
+        alt={alt}
+        className="max-h-full max-w-full rounded-lg object-contain shadow-2xl"
+      />
+    </div>,
+    document.body
+  );
+}
@@ -81,6 +81,7 @@ import {
 import { api, type ImportResult, type ImportBackupResult } from "../lib/api";
 import { eventBus } from "../lib/eventBus";
 import type { WSMessage, ImportProgressMessage } from "../lib/types";
+import { PathPickButton } from "./PathPickButton";

 type Mode = "rescan" | "path" | "upload" | "backup";

@@ -294,7 +295,7 @@ export function ImportHistory() {
            className="w-full flex items-center justify-between px-4 py-3 bg-surface-2 hover:bg-surface-3 transition-colors"
          >
            <span className="flex items-center gap-2 text-xs font-semibold text-fg-secondary uppercase tracking-wider">
-              <ListChecks className="w-3.5 h-3.5 text-blue-500" />
+              <ListChecks className="w-3.5 h-3.5 text-accent" />
              {t("import.instructions")}
            </span>
            <span className="text-[11px] text-fg-muted">{instructionsOpen ? "▾" : "▸"}</span>
@@ -426,14 +427,17 @@ export function ImportHistory() {
          {mode === "path" && (
            <div className="space-y-3">
              <div>
-                <input
-                  type="text"
-                  value={folderPath}
-                  onChange={(e) => setFolderPath(e.target.value)}
-                  placeholder={t("import.folderPlaceholder")}
-                  className="input w-full text-sm font-mono"
-                  spellCheck={false}
-                />
+                <div className="flex gap-1.5">
+                  <input
+                    type="text"
+                    value={folderPath}
+                    onChange={(e) => setFolderPath(e.target.value)}
+                    placeholder={t("import.folderPlaceholder")}
+                    className="input w-full text-sm font-mono"
+                    spellCheck={false}
+                  />
+                  <PathPickButton start={folderPath} onPick={setFolderPath} />
+                </div>
                <p className="text-[11px] text-fg-muted mt-1.5">{t("import.folderHelper")}</p>
              </div>
              <div className="flex justify-end">
@@ -455,8 +459,8 @@ export function ImportHistory() {

          {mode === "upload" && (
            <div className="space-y-3">
-              <div
-                onClick={() => fileInputRef.current?.click()}
+              <label
+                htmlFor="import-upload-files"
                onDragOver={(e) => {
                  e.preventDefault();
                  setDragging(true);
@@ -467,9 +471,9 @@ export function ImportHistory() {
                  setDragging(false);
                  onSelectFiles(e.dataTransfer.files);
                }}
-                className={`border-2 border-dashed rounded-lg px-4 py-8 text-center cursor-pointer transition-colors ${
+                className={`block border-2 border-dashed rounded-lg px-4 py-8 text-center cursor-pointer transition-colors focus-within:ring-2 focus-within:ring-accent/50 ${
                  dragging
-                    ? "border-blue-500 bg-blue-600/5"
+                    ? "border-accent bg-accent/5"
                    : "border-border hover:border-border-light bg-surface-1"
                }`}
              >
@@ -477,14 +481,15 @@ export function ImportHistory() {
                <p className="text-sm text-fg-secondary">{t("import.dropzoneHint")}</p>
                <p className="text-[11px] text-fg-muted mt-1">{t("import.dropzoneSub")}</p>
                <input
+                  id="import-upload-files"
                  ref={fileInputRef}
                  type="file"
                  multiple
                  accept=".jsonl,.json,.zip,.tar,.tgz,.gz,application/gzip,application/zip,application/x-tar,application/octet-stream"
                  onChange={(e) => onSelectFiles(e.target.files)}
-                  className="hidden"
+                  className="sr-only"
                />
-              </div>
+              </label>
              {files.length > 0 && (
                <div className="flex flex-wrap items-center justify-between gap-2 text-xs bg-surface-3 rounded-md px-3 py-2">
                  <span className="text-fg-secondary">
@@ -522,8 +527,8 @@ export function ImportHistory() {

          {mode === "backup" && (
            <div className="space-y-3">
-              <div
-                onClick={() => backupInputRef.current?.click()}
+              <label
+                htmlFor="import-backup-file"
                onDragOver={(e) => {
                  e.preventDefault();
                  setDragging(true);
@@ -535,9 +540,9 @@ export function ImportHistory() {
                  const f = e.dataTransfer.files?.[0];
                  if (f) setBackupFile(f);
                }}
-                className={`border-2 border-dashed rounded-lg px-4 py-8 text-center cursor-pointer transition-colors ${
+                className={`block border-2 border-dashed rounded-lg px-4 py-8 text-center cursor-pointer transition-colors focus-within:ring-2 focus-within:ring-accent/50 ${
                  dragging
-                    ? "border-blue-500 bg-blue-600/5"
+                    ? "border-accent bg-accent/5"
                    : "border-border hover:border-border-light bg-surface-1"
                }`}
              >
@@ -545,13 +550,14 @@ export function ImportHistory() {
                <p className="text-sm text-fg-secondary">{t("import.backupHint")}</p>
                <p className="text-[11px] text-fg-muted mt-1">{t("import.backupSub")}</p>
                <input
+                  id="import-backup-file"
                  ref={backupInputRef}
                  type="file"
                  accept=".json,application/json"
                  onChange={(e) => setBackupFile(e.target.files?.[0] || null)}
-                  className="hidden"
+                  className="sr-only"
                />
-              </div>
+              </label>
              {backupFile && (
                <div className="flex flex-wrap items-center justify-between gap-2 text-xs bg-surface-3 rounded-md px-3 py-2">
                  <span className="text-fg-secondary min-w-0">
@@ -591,7 +597,7 @@ export function ImportHistory() {
        {/* In-flight progress */}
        {running && progressText && (
          <div className="flex items-center gap-2 text-xs text-fg-secondary bg-surface-2 border border-border rounded-md px-3 py-2">
-            <Loader2 className="w-3.5 h-3.5 animate-spin text-blue-500 flex-shrink-0" />
+            <Loader2 className="w-3.5 h-3.5 animate-spin text-accent flex-shrink-0" />
            <span className="truncate">{progressText}</span>
            {progress?.current && (
              <code className="font-mono text-[11px] text-fg-muted truncate">
@@ -625,7 +631,7 @@ export function ImportHistory() {
              <ResultStat
                label={t("import.result.backfilled", { count: result.backfilled ?? 0 })}
                value={result.backfilled ?? 0}
-                color="text-blue-400"
+                color="text-accent"
              />
              <ResultStat
                label={t("import.result.skipped", { count: result.skipped })}
@@ -672,12 +678,12 @@ export function ImportHistory() {
              <ResultStat
                label={t("import.backupResult.events", { count: backupResult.events })}
                value={backupResult.events}
-                color="text-violet-300"
+                color="text-fg-primary"
              />
              <ResultStat
                label={t("import.backupResult.pricing", { count: backupResult.model_pricing })}
                value={backupResult.model_pricing}
-                color="text-cyan-300"
+                color="text-cyan-700 dark:text-cyan-300"
              />
            </div>
            <p className="text-[11px] text-fg-muted">
@@ -728,16 +734,16 @@ function ModeButton({
 }) {
  return (
    <button
+      type="button"
+      aria-pressed={active}
      onClick={onClick}
      className={`text-left p-3 rounded-lg border transition-colors ${
-        active
-          ? "border-blue-600/40 bg-blue-600/10"
-          : "border-border bg-surface-2 hover:bg-surface-3"
+        active ? "border-accent/40 bg-accent/10" : "border-border bg-surface-2 hover:bg-surface-3"
      }`}
    >
      <div
        className={`flex items-center gap-1.5 text-xs font-medium mb-1 ${
-          active ? "text-blue-400" : "text-fg-secondary"
+          active ? "text-accent" : "text-fg-secondary"
        }`}
      >
        {icon}
@@ -1,7 +1,9 @@
 /**
 * @file Layout.tsx
 * @description Application shell that frames every authenticated route: persistent
- * sidebar, main content column, update notifier, and the Sagi assistant overlay.
+ * sidebar, main content column, the bottom status bar, update notifier, and the
+ * Sagi assistant overlay. The connection details modal's open state lives here
+ * because both the sidebar's rail button and the status bar open it.
 * The layout is the single parent route in {@link App} — child pages render inside
 * React Router's `<Outlet />` so navigation never remounts chrome.
 *
@@ -10,6 +12,17 @@
 * written back on every toggle. Failures to access storage are swallowed so a
 * private-browsing quota error never breaks the UI.
 *
+ * ## Sidebar width
+ * The expanded sidebar's right edge drags (or takes ←/→) between
+ * {@link SIDEBAR_MIN} and {@link SIDEBAR_MAX} px — never past 40% of the
+ * window — kept in `agenthub.sidebar.width`; a double-click resets it.
+ *
+ * ## Narrow viewports
+ * With no stored preference the sidebar starts collapsed below `lg` (see
+ * {@link loadCollapsed}). Below `md` it leaves the flow entirely: a menu
+ * button in a slim top bar opens it as an off-canvas drawer (a modal dialog —
+ * backdrop, Escape, focus trapped and restored), which closes on navigation.
+ *
 * ## Sticky descendants
 * The inner content wrapper uses `overflow-x-clip` (not `hidden`) so horizontal
 * overflow is clipped without creating a scroll container. That keeps `position:
@@ -38,7 +51,8 @@
 * ## Internal dependencies
 * - `./Sidebar`
 * - `./UpdateNotifier`
- * - `./Sagi/Sagi`
+ * - `./lanes/InterruptedSessionsPrompt` (the "resume interrupted sessions?" dialog)
+ * - `./Sagi/SagiMount`
 *
 * ## Public surface
 * - `Layout` — exported API; see TSDoc on the symbol for behavior.
@@ -62,12 +76,57 @@
 *
 * ----------------------------------------------------------------------------- */

-import { useState, useCallback } from "react";
-import { Outlet } from "react-router-dom";
+import { lazy, Suspense, useState, useCallback, useEffect, useSyncExternalStore } from "react";
+import { Outlet, useLocation } from "react-router-dom";
+import { Menu } from "lucide-react";
 import { useTranslation } from "react-i18next";
 import { Sidebar, SIDEBAR_STORAGE_KEY, loadCollapsed } from "./Sidebar";
 import { UpdateNotifier } from "./UpdateNotifier";
-import { Sagi } from "./Sagi/Sagi";
+import { InterruptedSessionsPrompt } from "./lanes/InterruptedSessionsPrompt";
+import { SagiMount } from "./Sagi/SagiMount";
+import { StatusBar } from "./StatusBar";
+import { useOnboarding } from "../lib/userPrefs";
+import { OnboardingTour } from "./onboarding/OnboardingTour";
+
+// Loaded only for an account that has not finished onboarding: the wizard
+// carries the appearance, pet and notification settings screens.
+const OnboardingWizard = lazy(() =>
+  import("./onboarding/OnboardingWizard").then((m) => ({ default: m.OnboardingWizard }))
+);
+
+const WIDTH_KEY = "agenthub.sidebar.width";
+/** The default width, and the narrowest the edge drags to. */
+export const SIDEBAR_MIN = 240;
+/** Wide enough for long workspace names on a large screen, no wider. */
+export const SIDEBAR_MAX = 480;
+
+/** A width inside the bounds, and at most 40% of the window. */
+export function clampSidebar(px: number): number {
+  const max = Math.max(SIDEBAR_MIN, Math.min(SIDEBAR_MAX, window.innerWidth * 0.4));
+  return Math.round(Math.min(max, Math.max(SIDEBAR_MIN, px)));
+}
+
+function loadWidth(): number {
+  try {
+    const n = Number(localStorage.getItem(WIDTH_KEY));
+    if (n) return clampSidebar(n);
+  } catch {}
+  return SIDEBAR_MIN;
+}
+
+/** Below Tailwind's `md`: the sidebar becomes an off-canvas drawer. */
+export const DRAWER_QUERY = "(max-width: 767.98px)";
+
+function useMedia(query: string): boolean {
+  return useSyncExternalStore(
+    (cb) => {
+      const mq = window.matchMedia?.(query);
+      mq?.addEventListener?.("change", cb);
+      return () => mq?.removeEventListener?.("change", cb);
+    },
+    () => window.matchMedia?.(query).matches ?? false
+  );
+}

 /** Props for {@link Layout}. */
 interface LayoutProps {
@@ -82,6 +141,30 @@ interface LayoutProps {
 export function Layout({ wsConnected }: LayoutProps) {
  const { t } = useTranslation("nav");
  const [collapsed, setCollapsed] = useState(loadCollapsed);
+  const [connectionOpen, setConnectionOpen] = useState(false);
+  const onboarding = useOnboarding();
+  const [updateAvailable, setUpdateAvailable] = useState(false);
+  const drawer = useMedia(DRAWER_QUERY);
+  const [drawerOpen, setDrawerOpen] = useState(false);
+  const closeDrawer = useCallback(() => setDrawerOpen(false), []);
+  const { pathname, search } = useLocation();
+  const [width, setWidth] = useState(loadWidth);
+  const [resizing, setResizing] = useState(false);
+  const sidebarWidth = drawer ? "0rem" : collapsed ? "4.25rem" : `${width}px`;
+
+  const saveWidth = useCallback((px: number) => {
+    const next = clampSidebar(px);
+    setWidth(next);
+    try {
+      localStorage.setItem(WIDTH_KEY, String(next));
+    } catch {}
+  }, []);
+
+  // A pick in the drawer navigates; the drawer has done its job.
+  useEffect(closeDrawer, [pathname, search, closeDrawer]);
+  useEffect(() => {
+    if (!drawer) setDrawerOpen(false);
+  }, [drawer]);

  const toggle = useCallback(() => {
    setCollapsed((prev) => {
@@ -99,17 +182,97 @@ export function Layout({ wsConnected }: LayoutProps) {
        {t("skipToContent")}
      </a>
      <UpdateNotifier />
-      <Sagi />
-      <Sidebar wsConnected={wsConnected} collapsed={collapsed} onToggle={toggle} />
+      <InterruptedSessionsPrompt />
+      <SagiMount />
+      {onboarding.loaded && !onboarding.onboardedAt && (
+        <Suspense fallback={null}>
+          <OnboardingWizard />
+        </Suspense>
+      )}
+      <OnboardingTour />
+      {drawer && drawerOpen && (
+        <div
+          aria-hidden
+          data-testid="sidebar-backdrop"
+          onClick={closeDrawer}
+          className="fixed inset-0 z-40 bg-black/50 animate-fade-in"
+        />
+      )}
+      <Sidebar
+        wsConnected={wsConnected}
+        collapsed={drawer ? false : collapsed}
+        onToggle={drawer ? closeDrawer : toggle}
+        drawer={drawer ? { open: drawerOpen, onClose: closeDrawer } : undefined}
+        connectionOpen={connectionOpen}
+        onConnectionOpenChange={setConnectionOpen}
+        onUpdateAvailableChange={setUpdateAvailable}
+        width={width}
+        resizing={resizing}
+      />
+      {!drawer && !collapsed && (
+        <div
+          role="separator"
+          tabIndex={0}
+          aria-orientation="vertical"
+          aria-valuenow={width}
+          aria-valuemin={SIDEBAR_MIN}
+          aria-valuemax={SIDEBAR_MAX}
+          aria-label={t("resizeSidebar")}
+          title={t("resizeSidebar")}
+          data-testid="sidebar-resize"
+          className={`fixed top-0 bottom-0 z-30 w-1.5 -translate-x-1/2 cursor-col-resize outline-none transition-colors hover:bg-accent/40 focus-visible:bg-accent/60 ${
+            resizing ? "bg-accent/60" : ""
+          }`}
+          style={{ left: width }}
+          onPointerDown={(e) => {
+            e.preventDefault();
+            e.currentTarget.setPointerCapture?.(e.pointerId);
+            setResizing(true);
+          }}
+          onPointerMove={(e) => {
+            if (resizing) setWidth(clampSidebar(e.clientX));
+          }}
+          onPointerUp={(e) => {
+            if (!resizing) return;
+            setResizing(false);
+            saveWidth(e.clientX);
+          }}
+          onPointerCancel={() => setResizing(false)}
+          onDoubleClick={() => saveWidth(SIDEBAR_MIN)}
+          onKeyDown={(e) => {
+            if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+            e.preventDefault();
+            saveWidth(width + (e.key === "ArrowRight" ? 16 : -16));
+          }}
+        />
+      )}
      <main
        id="main-content"
        tabIndex={-1}
-        className="min-h-screen min-w-0 transition-[margin-left,width] duration-200 outline-none"
+        className={`min-h-screen min-w-0 pb-6 duration-200 outline-none ${
+          resizing ? "" : "transition-[margin-left,width]"
+        }`}
        style={{
-          marginLeft: collapsed ? "4.25rem" : "15rem",
-          width: collapsed ? "calc(100% - 4.25rem)" : "calc(100% - 15rem)",
+          marginLeft: sidebarWidth,
+          width: `calc(100% - ${sidebarWidth})`,
        }}
      >
+        {drawer && (
+          <div className="sticky top-0 z-20 flex h-11 items-center gap-2 border-b border-border bg-surface-1 px-2">
+            <button
+              type="button"
+              data-testid="sidebar-open"
+              onClick={() => setDrawerOpen(true)}
+              aria-label={t("openMenu")}
+              aria-expanded={drawerOpen}
+              title={t("openMenu")}
+              className="btn-icon"
+            >
+              <Menu className="h-5 w-5" aria-hidden />
+            </button>
+            <span className="text-sm font-semibold text-fg-primary">{t("brand")}</span>
+          </div>
+        )}
        {/* overflow-x-clip (not -hidden) clips horizontal overflow without
            creating a scroll container, so descendant `position: sticky`
            elements (e.g. the Settings page TOC) still pin to the window. */}
@@ -117,6 +280,12 @@ export function Layout({ wsConnected }: LayoutProps) {
          <Outlet />
        </div>
      </main>
+      <StatusBar
+        wsConnected={wsConnected}
+        left={sidebarWidth}
+        onConnectionClick={() => setConnectionOpen(true)}
+        updateAvailable={updateAvailable}
+      />
    </div>
  );
 }
@@ -0,0 +1,44 @@
+/**
+ * @file MarkdownPreview.tsx
+ * @description A markdown file rendered for reading (GitHub-flavoured:
+ * tables, task lists, strikethrough, autolinks), shared by the config
+ * explorer's file viewer and the lane Changes panel. Raw HTML in the file is
+ * shown as text, never run (react-markdown without rehype-raw), and links
+ * open in a new tab. A leading YAML frontmatter block (skills, agents) is
+ * shown as a code block instead of being misread as a heading. `isMarkdown`
+ * says which paths get the preview toggle.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+/** Whether `path` names a markdown file. */
+export function isMarkdown(path: string | null | undefined): boolean {
+  return !!path && /\.(md|markdown|mdx)$/i.test(path);
+}
+
+/** Split a leading `---` frontmatter block off the body. */
+function splitFrontmatter(text: string): { front: string | null; body: string } {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
+  return m ? { front: m[1]!, body: text.slice(m[0].length) } : { front: null, body: text };
+}
+
+export function MarkdownPreview({ text, className = "" }: { text: string; className?: string }) {
+  const { front, body } = splitFrontmatter(text);
+  return (
+    <div data-testid="markdown-preview" className={`md-preview ${className}`}>
+      {front !== null && <pre className="md-frontmatter">{front}</pre>}
+      <ReactMarkdown
+        remarkPlugins={[remarkGfm]}
+        components={{
+          a: ({ node: _node, ...props }) => (
+            <a {...props} target="_blank" rel="noreferrer noopener" />
+          ),
+        }}
+      >
+        {body}
+      </ReactMarkdown>
+    </div>
+  );
+}
@@ -0,0 +1,105 @@
+/**
+ * @file NeedsYouStrip.tsx
+ * @description The Dashboard's pinned "Needs you" strip: every active session
+ * blocked on the user (`awaiting_input_since`), each linking straight to its
+ * workspace pane (or replay), else its analysis page. Renders nothing while no
+ * session is waiting. `compact` is the one-line form shown above Analytics.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import { Link } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { BellRing } from "lucide-react";
+import { api, type RunHandle } from "../lib/api";
+import { timeAgo } from "../lib/format";
+import { useLiveRefresh } from "../hooks/useLiveRefresh";
+import { laneChangeMatcher, runKeyOf } from "../lib/laneChange";
+import { workspaceHref } from "./SessionRowMenu";
+import type { Session } from "../lib/types";
+
+export function NeedsYouStrip({ compact = false }: { compact?: boolean }) {
+  const { t } = useTranslation("dashboard");
+  const [sessions, setSessions] = useState<Session[]>([]);
+  // The real count: only the first 20 are fetched and listed.
+  const [total, setTotal] = useState(0);
+  const [runs, setRuns] = useState<RunHandle[]>([]);
+
+  const load = useCallback(() => {
+    api.sessions
+      .list({ awaiting: true, limit: 20 })
+      .then((r) => {
+        setSessions(r.sessions);
+        setTotal(r.total);
+      })
+      .catch(() => undefined); // the strip is a shortcut; the pages show errors
+  }, []);
+  // The live panes (for the links) move only when a lane's run columns do.
+  const loadRuns = useCallback(() => {
+    api.run
+      .list()
+      .then((r) => setRuns(r.items))
+      .catch(() => undefined);
+  }, []);
+
+  useEffect(() => {
+    load();
+    loadRuns();
+  }, [load, loadRuns]);
+  useLiveRefresh(load, {
+    intervalMs: 15000,
+    match: (msg) => msg.type === "session_updated" || msg.type === "session_created",
+  });
+  const [runChanged] = useState(() => laneChangeMatcher(runKeyOf));
+  useLiveRefresh(loadRuns, { intervalMs: 15000, match: runChanged });
+
+  if (sessions.length === 0) return null;
+
+  return (
+    <section
+      aria-label={t("needsYou.title")}
+      className={`card border-status-warning/40 ${compact ? "px-3 py-2" : "p-4"}`}
+    >
+      <div className={`flex flex-wrap items-center gap-2 ${compact ? "" : "mb-3"}`}>
+        <BellRing className="w-4 h-4 text-status-warning flex-shrink-0" aria-hidden />
+        <h2 className="text-sm font-medium text-fg-primary">
+          {t("needsYou.title")}{" "}
+          <span className="text-fg-muted font-normal">({Math.max(total, sessions.length)})</span>
+        </h2>
+        {compact &&
+          sessions.slice(0, 5).map((s) => (
+            <Link
+              key={s.id}
+              to={workspaceHref(s, runs) ?? `/sessions/${s.id}`}
+              className="text-xs px-2 py-0.5 rounded-full bg-status-warning/10 border border-status-warning/30 text-fg-secondary hover:text-fg-primary truncate max-w-[14rem]"
+            >
+              {s.name || s.id.slice(0, 8)}
+            </Link>
+          ))}
+      </div>
+      {!compact && (
+        <ul className="divide-y divide-border">
+          {sessions.map((s) => (
+            <li key={s.id}>
+              <Link
+                to={workspaceHref(s, runs) ?? `/sessions/${s.id}`}
+                className="flex items-center gap-3 py-2 px-1 hover:bg-surface-4 rounded"
+              >
+                <span className="w-2 h-2 rounded-full bg-status-warning flex-shrink-0" />
+                <span className="text-sm text-fg-secondary truncate flex-1">
+                  {s.name || s.id.slice(0, 8)}
+                </span>
+                <span className="text-[11px] text-fg-muted truncate max-w-[16rem]">{s.cwd}</span>
+                {s.awaiting_input_since && (
+                  <span className="text-[11px] text-fg-muted flex-shrink-0">
+                    {t("needsYou.since", { ago: timeAgo(s.awaiting_input_since) })}
+                  </span>
+                )}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}
@@ -1,18 +1,25 @@
 /**
 * @file PageTabs.tsx
 * @description Shared top-of-page tab bar used by the pages that merged several
- * former routes into one (Settings hub, Sessions/Events history). Rendering only -
- * the owning page keeps the active tab in its own query param.
+ * former routes into one (Settings hub, Sessions/Events history). The owning
+ * page keeps the active tab in its own query param. `actions` sits at the bar's
+ * right edge, outside the tablist.
+ *
+ * These are real in-page tabs (one view swapped in place), so they follow the
+ * WAI-ARIA tabs pattern: one tab stop (roving tabindex), Left/Right/Home/End
+ * move AND select. Pass the active view as `children` and it is wrapped in the
+ * `role="tabpanel"` the tabs point at with `aria-controls`; without children no
+ * `aria-controls` is emitted (it would name an element that does not exist).
+ * The selected tab is marked by weight and an underline, not colour alone.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
-import type { ComponentType } from "react";
+
+import { useId, type ComponentType, type KeyboardEvent, type ReactNode } from "react";

 export interface PageTab {
  id: string;
  label: string;
  Icon: ComponentType<{ className?: string }>;
-  /** Small muted suffix, e.g. "soon" for a tool that is not integrated yet. */
-  badge?: string;
 }

 interface PageTabsProps {
@@ -20,41 +27,94 @@ interface PageTabsProps {
  activeId: string;
  onSelect: (id: string) => void;
  ariaLabel: string;
+  /** Buttons at the right edge of the bar (not tabs). */
+  actions?: ReactNode;
+  /** The active tab's view, rendered inside its `role="tabpanel"`. */
+  children?: ReactNode;
 }

-/**
- * Horizontal tab strip for a page that hosts several panels.
- * @param props - Tabs to render, the active tab id, and the selection callback.
- * @returns The tab bar element.
- */
-export function PageTabs({ tabs, activeId, onSelect, ariaLabel }: PageTabsProps) {
-  return (
+export function PageTabs({
+  tabs,
+  activeId,
+  onSelect,
+  ariaLabel,
+  actions,
+  children,
+}: PageTabsProps) {
+  const base = useId();
+  const tabId = (id: string) => `${base}-tab-${id}`;
+  const panelId = `${base}-panel`;
+  const hasPanel = children !== undefined;
+
+  const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    const i = tabs.findIndex((t) => t.id === activeId);
+    const last = tabs.length - 1;
+    const next =
+      e.key === "ArrowRight"
+        ? (i + 1) % tabs.length
+        : e.key === "ArrowLeft"
+          ? (i - 1 + tabs.length) % tabs.length
+          : e.key === "Home"
+            ? 0
+            : e.key === "End"
+              ? last
+              : -1;
+    const tab = tabs[next];
+    if (!tab) return;
+    e.preventDefault();
+    onSelect(tab.id);
+    document.getElementById(tabId(tab.id))?.focus();
+  };
+
+  const list = (
    <div
      role="tablist"
      aria-label={ariaLabel}
-      className="flex items-center gap-1.5 overflow-x-auto no-scrollbar border-b border-border/60 pb-2"
+      onKeyDown={onKeyDown}
+      className={`flex items-center gap-1.5 overflow-x-auto no-scrollbar ${
+        actions ? "min-w-0 flex-1" : "border-b border-border/60 pb-2"
+      }`}
    >
-      {tabs.map(({ id, label, Icon, badge }) => {
+      {tabs.map(({ id, label, Icon }) => {
        const isActive = id === activeId;
        return (
          <button
            key={id}
+            id={tabId(id)}
            type="button"
            role="tab"
            aria-selected={isActive}
+            aria-controls={hasPanel && isActive ? panelId : undefined}
+            tabIndex={isActive ? 0 : -1}
            onClick={() => onSelect(id)}
-            className={`inline-flex items-center gap-1.5 text-xs whitespace-nowrap px-3 py-1.5 rounded-lg border transition-colors flex-shrink-0 ${
+            className={`inline-flex items-center gap-1.5 text-xs font-medium whitespace-nowrap px-3 py-1.5 rounded-lg border transition-colors flex-shrink-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 ${
              isActive
-                ? "bg-accent/15 border-accent/30 text-accent"
+                ? "bg-accent/15 border-accent/30 text-accent shadow-[inset_0_-2px_0_rgb(var(--accent))]"
                : "border-border text-fg-secondary hover:text-fg-primary hover:bg-surface-3"
            }`}
          >
            <Icon className="w-3.5 h-3.5" />
            {label}
-            {badge && <span className="text-[10px] text-fg-muted">{badge}</span>}
          </button>
        );
      })}
    </div>
  );
+  const bar = actions ? (
+    <div className="flex items-center gap-3 border-b border-border/60 pb-2">
+      {list}
+      <div className="flex flex-shrink-0 items-center gap-1.5">{actions}</div>
+    </div>
+  ) : (
+    list
+  );
+  if (!hasPanel) return bar;
+  return (
+    <>
+      {bar}
+      <div role="tabpanel" id={panelId} aria-labelledby={tabId(activeId)}>
+        {children}
+      </div>
+    </>
+  );
 }
@@ -0,0 +1,78 @@
+/**
+ * @file PathPickButton.tsx
+ * @description The one "Browse" button beside every path field: it asks the
+ * server to open the operating system's own folder/file picker
+ * (`POST /api/lanes/pick-path`) and fills the field with the absolute path the
+ * user chose. A browser's picker cannot give a page that path, so the dialog
+ * opens on the server's desktop — which is only this user's screen when the
+ * browser runs on the same machine. Anywhere else (a LAN browser, a server
+ * with no desktop or no zenity/kdialog) it falls back to the in-app
+ * `FolderBrowseModal` (as it does on any other failure) — for a file field
+ * too, which then lists files and picks one on click.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { FolderOpen } from "lucide-react";
+import { api } from "../lib/api";
+import { FolderBrowseModal } from "./lanes/FolderBrowseModal";
+
+export function PathPickButton({
+  kind = "dir",
+  start,
+  onPick,
+  showLabel = false,
+}: {
+  kind?: "dir" | "file";
+  /** The field's current value — the picker opens there. */
+  start?: string;
+  onPick: (path: string) => void;
+  showLabel?: boolean;
+}) {
+  const { t } = useTranslation(["lanes"]);
+  const [busy, setBusy] = useState(false);
+  const [fallback, setFallback] = useState(false);
+  const title = kind === "dir" ? t("browse.title") : t("browse.fileTitle");
+
+  const pick = async () => {
+    setBusy(true);
+    try {
+      const r = await api.lanes.pickPath(kind, start?.trim() || undefined);
+      if (r.path) onPick(r.path);
+    } catch {
+      // The in-app browser is the fallback whatever went wrong with the
+      // native one: a LAN browser (EREMOTE), no desktop, a crashed dialog.
+      setFallback(true);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <>
+      <button
+        type="button"
+        onClick={pick}
+        disabled={busy}
+        title={title}
+        aria-label={title}
+        className="flex shrink-0 items-center gap-1 self-stretch rounded-md border border-border-light px-2 text-xs text-fg-secondary hover:bg-surface-2 disabled:opacity-50"
+      >
+        <FolderOpen className="h-3.5 w-3.5" />
+        {showLabel && t("browse.button")}
+      </button>
+      {/* Its clicks stay here: a backdrop click must close only this modal,
+        not bubble on to a dialog this button sits in. */}
+      <div className="contents" onClick={(e) => e.stopPropagation()}>
+        <FolderBrowseModal
+          open={fallback}
+          kind={kind}
+          initialPath={start?.trim() || undefined}
+          onSelect={onPick}
+          onClose={() => setFallback(false)}
+        />
+      </div>
+    </>
+  );
+}
@@ -1,7 +1,8 @@
 /**
 * @file RemoteSources.tsx
 * @description Settings UI for the Remote Data Sources feature: manage the SSH
- * machines this dashboard pulls Claude Code history from, and choose the global
+ * machines this dashboard pulls Claude Code (and, opted in per source, Codex)
+ * history from, and choose the global
 * "data scope" (which machines' data the whole app shows).
 *
 * Backs `server/routes/remote-sources.js` via {@link api.remoteSources} and the
@@ -9,7 +10,8 @@
 * here — authentication defers to the host's SSH stack (~/.ssh/config, agent,
 * keys, known_hosts); a source is just a label + ssh destination (+ optional
 * port / identity file / remote home). Live status/sync updates arrive over the
- * `remote_source.status` WebSocket message.
+ * `remote_source.status` WebSocket message. A right-click on a source opens
+ * its Test / Sync / Enable-Disable / Edit / Delete (plus Copy host) as a menu.
 *
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
@@ -57,6 +59,8 @@
 *
 * ----------------------------------------------------------------------------- */

+import { Checkbox } from "./Checkbox";
+import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "./ContextMenu";
 import { useCallback, useEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
 import {
@@ -79,9 +83,14 @@ import {
 import { api } from "../lib/api";
 import type { RemoteSource, RemoteSourceInput } from "../lib/api";
 import { eventBus } from "../lib/eventBus";
+import { toast } from "../lib/toast";
 import { isRemoteDataRefreshMessage } from "../lib/remoteDataEvents";
 import { useDataScope } from "../lib/dataScope";
 import type { ScopeMode } from "../lib/dataScope";
+import { PathPickButton } from "./PathPickButton";
+
+/** Data-scope choices in display order (the radio group's arrow-key order). */
+const SCOPE_MODES: ScopeMode[] = ["all", "local", "selected"];

 const EMPTY_FORM: RemoteSourceInput = {
  label: "",
@@ -89,6 +98,8 @@ const EMPTY_FORM: RemoteSourceInput = {
  ssh_port: null,
  identity_file: "",
  remote_home: "",
+  sync_codex: false,
+  remote_codex_home: "",
  enabled: true,
 };

@@ -134,6 +145,13 @@ export function RemoteSources() {
  const [formError, setFormError] = useState<string | null>(null);

  const [busyId, setBusyId] = useState<string | null>(null);
+  const ctx = useContextMenu<RemoteSource>();
+  // A menu item: close the menu, then act on the source it was opened on.
+  const pick = (fn: (s: RemoteSource) => unknown) => () => {
+    const s = ctx.menu?.item;
+    ctx.close();
+    if (s) fn(s);
+  };
  const [syncingAll, setSyncingAll] = useState(false);
  const [testResults, setTestResults] = useState<Record<string, { ok: boolean; message: string }>>(
    {}
@@ -204,6 +222,8 @@ export function RemoteSources() {
      ssh_port: s.ssh_port,
      identity_file: s.identity_file || "",
      remote_home: s.remote_home || "",
+      sync_codex: !!s.sync_codex,
+      remote_codex_home: s.remote_codex_home || "",
      enabled: s.enabled,
    });
    setEditingId(s.id);
@@ -227,6 +247,8 @@ export function RemoteSources() {
      ssh_port: form.ssh_port ? Number(form.ssh_port) : null,
      identity_file: form.identity_file?.trim() ? form.identity_file.trim() : null,
      remote_home: form.remote_home?.trim() ? form.remote_home.trim() : null,
+      sync_codex: !!form.sync_codex,
+      remote_codex_home: form.remote_codex_home?.trim() ? form.remote_codex_home.trim() : null,
      enabled: form.enabled,
    };
    try {
@@ -248,8 +270,8 @@ export function RemoteSources() {
    try {
      await api.remoteSources.update(s.id, { enabled: !s.enabled });
      load();
-    } catch {
-      /* surfaced via reload */
+    } catch (err) {
+      toast.error(err);
    } finally {
      setBusyId(null);
    }
@@ -291,8 +313,10 @@ export function RemoteSources() {
    try {
      await api.remoteSources.syncAll();
      load();
-    } catch {
-      /* per-source errors surface via each source's status on reload */
+    } catch (err) {
+      // Per-source errors still surface on each source's status after the reload.
+      toast.error(err);
+      load();
    } finally {
      setSyncingAll(false);
    }
@@ -306,8 +330,9 @@ export function RemoteSources() {
      await api.remoteSources.remove(id, purge);
      setConfirmDelete(null);
      load();
-    } catch {
-      /* surfaced via reload */
+    } catch (err) {
+      setConfirmDelete(null);
+      toast.error(err);
    } finally {
      setBusyId(null);
    }
@@ -348,7 +373,26 @@ export function RemoteSources() {
        </p>
        {/* Card selector — one card per scope mode, each with a short explanation
            so the choice is self-describing rather than a bare radio label. */}
-        <div className="grid gap-2.5 sm:grid-cols-3" role="radiogroup" aria-label="Data scope">
+        <div
+          className="grid gap-2.5 sm:grid-cols-3"
+          role="radiogroup"
+          aria-label={t("remoteSources.scopeTitle", "Data scope")}
+          onKeyDown={(e) => {
+            // Arrow keys move the choice, like a native radio group.
+            const step =
+              e.key === "ArrowRight" || e.key === "ArrowDown"
+                ? 1
+                : e.key === "ArrowLeft" || e.key === "ArrowUp"
+                  ? -1
+                  : 0;
+            if (!step) return;
+            e.preventDefault();
+            const i = SCOPE_MODES.indexOf(scope.mode);
+            const next = SCOPE_MODES[(i + step + SCOPE_MODES.length) % SCOPE_MODES.length]!;
+            setMode(next);
+            e.currentTarget.querySelector<HTMLElement>(`[data-mode="${next}"]`)?.focus();
+          }}
+        >
          {(
            [
              {
@@ -384,8 +428,11 @@ export function RemoteSources() {
            return (
              <button
                key={mode}
+                type="button"
                role="radio"
                aria-checked={active}
+                tabIndex={active ? 0 : -1}
+                data-mode={mode}
                onClick={() => setMode(mode)}
                className={`relative text-left rounded-xl border p-3 transition-colors ${
                  active
@@ -482,7 +529,7 @@ export function RemoteSources() {
              </label>
              <input
                className="input w-full"
-                placeholder="Dev box"
+                placeholder={t("remoteSources.fieldLabelPlaceholder", "Dev box")}
                value={form.label}
                onChange={(e) => setForm((f) => ({ ...f, label: e.target.value }))}
              />
@@ -519,12 +566,19 @@ export function RemoteSources() {
              <label className="block text-xs text-fg-muted mb-1">
                {t("remoteSources.fieldIdentity", "Identity file (optional)")}
              </label>
-              <input
-                className="input w-full font-mono"
-                placeholder="~/.ssh/id_ed25519"
-                value={form.identity_file ?? ""}
-                onChange={(e) => setForm((f) => ({ ...f, identity_file: e.target.value }))}
-              />
+              <div className="flex gap-1.5">
+                <input
+                  className="input w-full font-mono"
+                  placeholder="~/.ssh/id_ed25519"
+                  value={form.identity_file ?? ""}
+                  onChange={(e) => setForm((f) => ({ ...f, identity_file: e.target.value }))}
+                />
+                <PathPickButton
+                  kind="file"
+                  start={form.identity_file || "~/.ssh"}
+                  onPick={(p) => setForm((f) => ({ ...f, identity_file: p }))}
+                />
+              </div>
            </div>
            <div className="sm:col-span-2">
              <label className="block text-xs text-fg-muted mb-1">
@@ -544,17 +598,37 @@ export function RemoteSources() {
              </p>
            </div>
          </div>
-          <label className="flex items-center gap-2 cursor-pointer">
-            <input
-              type="checkbox"
-              className="accent-accent"
-              checked={!!form.enabled}
-              onChange={(e) => setForm((f) => ({ ...f, enabled: e.target.checked }))}
-            />
-            <span className="text-sm text-fg-secondary">
-              {t("remoteSources.fieldEnabled", "Sync automatically in the background")}
-            </span>
-          </label>
+          <Checkbox
+            checked={!!form.sync_codex}
+            onChange={(v) => setForm((f) => ({ ...f, sync_codex: v }))}
+            label={t("remoteSources.fieldSyncCodex", "Also pull Codex sessions")}
+            labelClassName="text-sm text-fg-secondary"
+          />
+          {form.sync_codex && (
+            <div>
+              <label className="block text-xs text-fg-muted mb-1">
+                {t("remoteSources.fieldRemoteCodexHome", "Remote Codex home (optional)")}
+              </label>
+              <input
+                className="input w-full font-mono"
+                placeholder="~/.codex"
+                value={form.remote_codex_home ?? ""}
+                onChange={(e) => setForm((f) => ({ ...f, remote_codex_home: e.target.value }))}
+              />
+              <p className="mt-1 text-[11px] text-fg-muted leading-snug">
+                {t(
+                  "remoteSources.fieldRemoteCodexHomeHint",
+                  "Default ~/.codex (wsl:~/.codex when the Claude home is in WSL). Its sessions/ folder is copied, and the sessions show up as Codex sessions of this source, with their tokens and cost."
+                )}
+              </p>
+            </div>
+          )}
+          <Checkbox
+            checked={!!form.enabled}
+            onChange={(v) => setForm((f) => ({ ...f, enabled: v }))}
+            label={t("remoteSources.fieldEnabled", "Sync automatically in the background")}
+            labelClassName="text-sm text-fg-secondary"
+          />
          {formError && (
            <div className="text-xs text-status-danger bg-status-danger/10 border border-status-danger/25 rounded-lg px-3 py-2">
              {formError}
@@ -602,7 +676,7 @@ export function RemoteSources() {
            const test = testResults[s.id];
            const busy = busyId === s.id;
            return (
-              <div key={s.id} className="card p-4">
+              <div key={s.id} onContextMenu={(e) => ctx.open(e, s)} className="card p-4">
                <div className="flex items-start justify-between gap-3 flex-wrap">
                  <div className="min-w-0">
                    <div className="flex items-center gap-2 flex-wrap">
@@ -632,6 +706,9 @@ export function RemoteSources() {
                      {s.host}
                      {s.ssh_port ? `:${s.ssh_port}` : ""}
                      {s.remote_home ? ` · ${s.remote_home}` : ""}
+                      {s.sync_codex
+                        ? ` · ${t("remoteSources.codexOn", "+ Codex")}${s.remote_codex_home ? ` (${s.remote_codex_home})` : ""}`
+                        : ""}
                    </div>
                    <div className="text-[11px] text-fg-muted mt-1">
                      {s.last_sync_at
@@ -647,9 +724,19 @@ export function RemoteSources() {
                        ` · ${t("remoteSources.syncOnRemote", "{{n}} on remote", {
                          n: s.last_sync_counts.sessions_tagged,
                        })}`}
+                      {s.last_sync_counts?.codex_sessions != null &&
+                        ` · ${t("remoteSources.syncCodex", "{{n}} Codex", {
+                          n: s.last_sync_counts.codex_sessions,
+                        })}`}
                    </div>
-                    {s.status === "error" && s.last_error && (
-                      <div className="text-[11px] text-status-danger mt-1 break-words">
+                    {/* A sync that pulled one CLI's history but not the other's is
+                        `ok` with the other's failure in last_error. */}
+                    {s.last_error && (s.status === "error" || s.status === "ok") && (
+                      <div
+                        className={`text-[11px] mt-1 break-words ${
+                          s.status === "error" ? "text-status-danger" : "text-status-warning"
+                        }`}
+                      >
                        {s.last_error}
                      </div>
                    )}
@@ -723,22 +810,16 @@ export function RemoteSources() {
                    <p className="text-xs text-fg-secondary mb-2">
                      {t("remoteSources.confirmDelete", "Remove this source?")}
                    </p>
-                    <label className="flex items-center gap-2 mb-3 cursor-pointer">
-                      <input
-                        type="checkbox"
-                        className="accent-red-500"
-                        checked={confirmDelete.purge}
-                        onChange={(e) =>
-                          setConfirmDelete((c) => c && { ...c, purge: e.target.checked })
-                        }
-                      />
-                      <span className="text-xs text-fg-secondary">
-                        {t(
-                          "remoteSources.purgeData",
-                          "Also delete the sessions imported from this source (cannot be undone)"
-                        )}
-                      </span>
-                    </label>
+                    <Checkbox
+                      className="mb-3"
+                      tone="danger"
+                      checked={confirmDelete.purge}
+                      onChange={(v) => setConfirmDelete((c) => c && { ...c, purge: v })}
+                      label={t(
+                        "remoteSources.purgeData",
+                        "Also delete the sessions imported from this source (cannot be undone)"
+                      )}
+                    />
                    <div className="flex items-center gap-2">
                      <button
                        onClick={doDelete}
@@ -763,6 +844,34 @@ export function RemoteSources() {
              </div>
            );
          })}
+          {ctx.menu && (
+            <ContextMenu
+              x={ctx.menu.x}
+              y={ctx.menu.y}
+              onClose={ctx.close}
+              testId="remote-source-menu"
+            >
+              <MenuItem disabled={busyId === ctx.menu.item.id} onSelect={pick(testSource)}>
+                {t("remoteSources.test", "Test")}
+              </MenuItem>
+              <MenuItem disabled={busyId === ctx.menu.item.id} onSelect={pick(syncNow)}>
+                {t("remoteSources.syncNow", "Sync")}
+              </MenuItem>
+              <MenuItem disabled={busyId === ctx.menu.item.id} onSelect={pick(toggleEnabled)}>
+                {ctx.menu.item.enabled
+                  ? t("remoteSources.disable", "Disable")
+                  : t("remoteSources.enable", "Enable")}
+              </MenuItem>
+              <MenuItem onSelect={pick(openEdit)}>{t("common:edit", "Edit")}</MenuItem>
+              <MenuItem onSelect={pick((s) => void navigator.clipboard.writeText(s.host))}>
+                {t("rowMenu.copyHost")}
+              </MenuItem>
+              <MenuSeparator />
+              <MenuItem danger onSelect={pick((s) => setConfirmDelete({ id: s.id, purge: false }))}>
+                {t("common:delete", "Delete")}
+              </MenuItem>
+            </ContextMenu>
+          )}
        </div>
      )}
    </div>
@@ -0,0 +1,84 @@
+/**
+ * @file RouteErrorBoundary.tsx
+ * @description Route-level error boundary around the lazily loaded pages. After
+ * a self-update an open tab still asks for the OLD `/assets/<Page>-<hash>.js`,
+ * which the SPA fallback answers with index.html, so the dynamic import
+ * rejects: that case reloads the page once (a sessionStorage guard stops a
+ * reload loop). Any other render error — or a second chunk failure — shows a
+ * themed "Something went wrong — Reload" panel instead of a blank app, until the
+ * route changes (`resetKey`): the lazy routes share one boundary instance, so
+ * an error on one page would otherwise stay on every other.
+ * `reloadOnce` is also used by App's `vite:preloadError` listener.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { Component, type ReactNode } from "react";
+import i18n from "../i18n";
+
+const RELOAD_KEY = "agenthub.chunkReloadAt";
+/** A second chunk failure within this window means the reload did not help. */
+const RELOAD_WINDOW_MS = 30_000;
+
+/** A failed dynamic `import()` (Chrome, Firefox, Safari wordings) or a ChunkLoadError. */
+export function isChunkLoadError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  return (
+    err.name === "ChunkLoadError" ||
+    /dynamically imported module|Importing a module script failed|error loading dynamically imported module|Unable to preload CSS/i.test(
+      err.message
+    )
+  );
+}
+
+/** Reload the page unless this tab already did so in the last 30 s. */
+export function reloadOnce(reload: () => void = () => window.location.reload()): boolean {
+  try {
+    const last = Number(sessionStorage.getItem(RELOAD_KEY) || 0);
+    if (Date.now() - last < RELOAD_WINDOW_MS) return false;
+    sessionStorage.setItem(RELOAD_KEY, String(Date.now()));
+  } catch {
+    return false; // no sessionStorage: no loop guard, so never auto-reload
+  }
+  reload();
+  return true;
+}
+
+interface Props {
+  children: ReactNode;
+  /** Injected in tests; defaults to `window.location.reload`. */
+  reload?: () => void;
+  /** A change (the route's path) clears a caught error. */
+  resetKey?: string;
+}
+
+export class RouteErrorBoundary extends Component<Props, { error: Error | null }> {
+  state = { error: null as Error | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  componentDidCatch(error: Error) {
+    if (isChunkLoadError(error)) reloadOnce(this.props.reload);
+  }
+
+  componentDidUpdate(prev: Props) {
+    if (this.state.error && prev.resetKey !== this.props.resetKey) this.setState({ error: null });
+  }
+
+  render() {
+    if (!this.state.error) return this.props.children;
+    const reload = this.props.reload ?? (() => window.location.reload());
+    return (
+      <div role="alert" className="card flex flex-col items-center gap-3 py-16 text-center">
+        <p className="text-sm font-medium text-fg-primary">
+          {i18n.t("dashboard:errorBoundary.title")}
+        </p>
+        <p className="text-xs text-fg-muted max-w-md">{i18n.t("dashboard:errorBoundary.body")}</p>
+        <button type="button" className="btn-primary text-sm" onClick={reload}>
+          {i18n.t("dashboard:errorBoundary.reload")}
+        </button>
+      </div>
+    );
+  }
+}
@@ -0,0 +1,591 @@
+/**
+ * @file PetChat.tsx
+ * @description The pet's chat window — its whole UI: clicking the pet opens
+ * it. Above the conversation sits what the pet knows (`info`: live / waiting /
+ * errored, the sessions that need you, Mute, Clear alerts — `SagiInfo.tsx`).
+ * Before a chat runs, a question the pet can answer itself (`onLocal`: status,
+ * who are you…) is answered right here; anything else — and every message once
+ * a chat runs — goes to the AI: the first message starts a
+ * session of the user's DEFAULT AI tool (`agenthub.defaultTool`, Claude or
+ * Codex — the two with a readable transcript) in the "Sagi" workspace, in its
+ * first free tab (`startInFreeTabDetailed`), and the conversation is shown as
+ * chat bubbles read from the session's transcript. Follow-ups are typed into
+ * that session's pane through a terminal attached OFF-SCREEN (`TerminalView`
+ * in a fixed box left of the viewport — `submitToRun` needs a mounted,
+ * attached pane, exactly like the workspace's own Chat view), so nothing new
+ * reaches the server. A menu the CLI asks with (a permission or trust prompt)
+ * is read off that pane and answered with `PaneMenuCard`. The chat is kept in
+ * `localStorage` (`agenthub.pet.chat`) while its pane lives, so closing and
+ * reopening the window continues it; **New chat** STOPS that session (kills
+ * its pane and archives it, asking first only mid-reply), **Open in workspace**
+ * opens its pane there. Opening never resumes an ended session: once the pane
+ * is gone, the next message starts a new one.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useCallback, useEffect, useRef, useState, type FormEvent, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { ArrowUp, ExternalLink, Loader2, SquarePen, Wrench, X } from "lucide-react";
+import { api } from "../../lib/api";
+import type { TranscriptMessage } from "../../lib/types";
+import { readDefaultMode, readDefaultTool } from "../../lib/sessionDefaults";
+import {
+  answerRunMenu,
+  chooseRunOption,
+  interruptRun,
+  readRunMenu,
+  submitToRun,
+  type PaneMenu,
+} from "../../lib/panePaste";
+import { isSubmitEnter } from "../../lib/keys";
+import { confirmDialog } from "../../lib/confirm";
+import { toast } from "../../lib/toast";
+import { startInFreeTabDetailed } from "../lanes/startSession";
+import { TerminalView } from "../run/TerminalView";
+import { PaneMenuCard } from "../run/PaneChat";
+import { MarkdownContent } from "../conversation/MarkdownContent";
+
+/** Tools whose session the chat can read back (a transcript AgentHub parses). */
+export const PET_CHAT_TOOLS = new Set(["claude", "codex"]);
+const CHAT_KEY = "agenthub.pet.chat";
+const POLL_MS = 1500;
+const MENU_POLL_MS = 700;
+// A follow-up waits this long for the off-screen pane to attach.
+const SEND_TRIES = 20;
+const SEND_RETRY_MS = 250;
+
+/** The session the chat is talking to. */
+export interface PetChatRef {
+  laneId: number;
+  runId: string;
+  tool: string;
+}
+
+export function readPetChat(): PetChatRef | null {
+  try {
+    const v = JSON.parse(localStorage.getItem(CHAT_KEY) ?? "null") as Partial<PetChatRef> | null;
+    if (
+      v &&
+      typeof v.laneId === "number" &&
+      typeof v.runId === "string" &&
+      typeof v.tool === "string"
+    )
+      return { laneId: v.laneId, runId: v.runId, tool: v.tool };
+  } catch {
+    /* unreadable: no chat */
+  }
+  return null;
+}
+
+function writePetChat(ref: PetChatRef | null) {
+  try {
+    if (ref) localStorage.setItem(CHAT_KEY, JSON.stringify(ref));
+    else localStorage.removeItem(CHAT_KEY);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** The tool a new chat starts: the user's default, when the chat can show it. */
+export function petChatTool(): string | null {
+  const tool = readDefaultTool() ?? "claude";
+  return PET_CHAT_TOOLS.has(tool) ? tool : null;
+}
+
+type Line =
+  | { key: string; role: "user" | "assistant"; text: string }
+  | { key: string; role: "tools"; names: string[] };
+
+/** A human line's text: Claude Code's own injected lines (`<command-…>`,
+ *  `<system-reminder>`…) are not something the user said. */
+const humanText = (m: TranscriptMessage) =>
+  m.content
+    .filter((c) => c.type === "text" && c.text)
+    .map((c) => c.text!.trim())
+    .filter((t) => t && !t.startsWith("<"))
+    .join("\n\n");
+
+/** The transcript as chat lines: the user's words, the assistant's prose, and
+ *  each run of tool calls between them folded into one chip. */
+export function chatLines(messages: TranscriptMessage[]): Line[] {
+  const out: Line[] = [];
+  messages.forEach((m, i) => {
+    const sender = m.sender ?? m.type;
+    if (sender === "user") {
+      const text = humanText(m);
+      if (text) out.push({ key: `u${i}`, role: "user", text });
+      return;
+    }
+    if (m.type !== "assistant") return;
+    m.content.forEach((c, j) => {
+      if (c.type === "text" && c.text?.trim()) {
+        out.push({ key: `a${i}-${j}`, role: "assistant", text: c.text.trim() });
+      } else if (c.type === "tool_use" && c.name) {
+        const last = out[out.length - 1];
+        if (last?.role === "tools") last.names.push(c.name);
+        else out.push({ key: `t${i}-${j}`, role: "tools", names: [c.name] });
+      }
+    });
+  });
+  return out;
+}
+
+/** Still working: the last line is the user's, or an assistant turn not ended. */
+function isBusy(messages: TranscriptMessage[]): boolean {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]!;
+    const sender = m.sender ?? m.type;
+    if (m.type === "assistant") return m.stop_reason !== undefined && m.stop_reason !== "end_turn";
+    if (sender === "user" && humanText(m)) return true;
+  }
+  return false;
+}
+
+/** "Read ×2 · Bash" */
+function toolSummary(names: string[]): string {
+  const counts = new Map<string, number>();
+  names.forEach((n) => counts.set(n, (counts.get(n) ?? 0) + 1));
+  return [...counts].map(([n, c]) => (c > 1 ? `${n} ×${c}` : n)).join(" · ");
+}
+
+/** What the container made of a message: an answer the pet gives itself, or
+ *  `handled` (it took the message elsewhere); null sends it to the AI. */
+export type PetLocalReply = { answer: string } | { handled: true } | null;
+
+interface PetChatProps {
+  /** The pet's shown name, for the header and greeting. */
+  name: string;
+  /** Shown in place of the plain name (the rename button). */
+  title?: ReactNode;
+  /** Extra header buttons, before Open in workspace (the pat heart). */
+  headerActions?: ReactNode;
+  /** Under the header: what the pet knows (status, sessions that need you). */
+  info?: ReactNode;
+  /** Asked first while no chat runs. */
+  onLocal?: (text: string) => PetLocalReply;
+  onClose: () => void;
+  /** Opens the chat's pane in its workspace. */
+  onOpenWorkspace: (laneId: number, runId: string) => void;
+  /** The thinking mood while a reply is being written. */
+  onBusy?: (busy: boolean) => void;
+}
+
+export function PetChat({
+  name,
+  title,
+  headerActions,
+  info,
+  onLocal,
+  onClose,
+  onOpenWorkspace,
+  onBusy,
+}: PetChatProps) {
+  const { t } = useTranslation("settings");
+  const [chat, setChat] = useState<PetChatRef | null>(readPetChat);
+  const [sessionId, setSessionId] = useState<string | null>(null);
+  const [messages, setMessages] = useState<TranscriptMessage[]>([]);
+  // Sent but not in the transcript yet.
+  const [pending, setPending] = useState<string | null>(null);
+  const [starting, setStarting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [draft, setDraft] = useState("");
+  const [menu, setMenu] = useState<PaneMenu | null>(null);
+  // The pet's own answers, given before any chat ran.
+  const [local, setLocal] = useState<Line[]>([]);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  const remember = (ref: PetChatRef | null) => {
+    writePetChat(ref);
+    setChat(ref);
+    setSessionId(null);
+    setMessages([]);
+    setMenu(null);
+  };
+
+  // A remembered chat whose pane is gone is over: forget it, the next message starts anew.
+  useEffect(() => {
+    if (!chat) return;
+    let live = true;
+    const check = () =>
+      api.run
+        .get(chat.runId)
+        .then((h) => {
+          if (!live) return;
+          if (h.status !== "running") remember(null);
+          else if (h.sessionId) setSessionId(h.sessionId);
+        })
+        .catch(() => live && remember(null));
+    void check();
+    // Codex learns its session only after a while; Claude's is known at start.
+    const timer = window.setInterval(() => {
+      if (!sessionId) void check();
+    }, POLL_MS);
+    return () => {
+      live = false;
+      window.clearInterval(timer);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chat?.runId, sessionId]);
+
+  // The conversation, polled while the window is open.
+  useEffect(() => {
+    if (!sessionId) return;
+    let live = true;
+    const load = () =>
+      api.sessions
+        .transcript(sessionId, { limit: 60 })
+        .then((r) => {
+          if (!live) return;
+          setMessages((prev) =>
+            prev.length === r.messages.length &&
+            JSON.stringify(prev[prev.length - 1]) ===
+              JSON.stringify(r.messages[r.messages.length - 1])
+              ? prev
+              : r.messages
+          );
+        })
+        .catch(() => undefined); // not started yet: the next poll asks again
+    void load();
+    const timer = window.setInterval(load, POLL_MS);
+    return () => {
+      live = false;
+      window.clearInterval(timer);
+    };
+  }, [sessionId]);
+
+  // A menu the CLI shows in the pane (permission, trust, a question).
+  useEffect(() => {
+    if (!chat) return;
+    const read = () =>
+      setMenu((prev) => {
+        const next = readRunMenu(chat.runId);
+        return JSON.stringify(next) === JSON.stringify(prev) ? prev : next;
+      });
+    const timer = window.setInterval(read, MENU_POLL_MS);
+    return () => window.clearInterval(timer);
+  }, [chat]);
+
+  const lines = [...local, ...chatLines(messages)];
+  // The pending line shows until the transcript has it.
+  useEffect(() => {
+    if (pending && lines.some((l) => l.role === "user" && l.text === pending.trim()))
+      setPending(null);
+  }, [lines, pending]);
+  const busy = starting || !!pending || isBusy(messages);
+  useEffect(() => onBusy?.(busy), [busy, onBusy]);
+  useEffect(() => () => onBusy?.(false), [onBusy]);
+
+  // Keep the newest in sight.
+  useEffect(() => {
+    const el = listRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [lines.length, pending, busy, menu]);
+
+  const send = useCallback(
+    async (text: string) => {
+      const prompt = text.trim();
+      if (!prompt || starting) return;
+      setError(null);
+      if (!chat && onLocal) {
+        const reply = onLocal(prompt);
+        if (reply && "handled" in reply) return;
+        if (reply) {
+          const n = Date.now();
+          setLocal((prev) => [
+            ...prev,
+            { key: `lu${n}`, role: "user", text: prompt },
+            { key: `la${n}`, role: "assistant", text: reply.answer },
+          ]);
+          return;
+        }
+      }
+      setPending(prompt);
+      if (chat) {
+        // Typed into the attached pane; it may still be attaching.
+        for (let i = 0; i < SEND_TRIES; i++) {
+          if (submitToRun(chat.runId, prompt)) return;
+          await new Promise((r) => setTimeout(r, SEND_RETRY_MS));
+        }
+        setPending(null);
+        setDraft(prompt);
+        setError(t("sagi.chat.notSent"));
+        return;
+      }
+      const tool = petChatTool() ?? "claude";
+      setStarting(true);
+      try {
+        const { lane } = await api.lanes.ensure({ title: "Sagi" });
+        const r = await startInFreeTabDetailed(lane.id, {
+          prompt,
+          ...(tool !== lane.tool ? { tool } : {}),
+          ...(tool === "claude" ? { permissionMode: readDefaultMode() } : {}),
+        });
+        remember({ laneId: r.laneId, runId: r.runId, tool });
+      } catch (err) {
+        setPending(null);
+        setDraft(prompt);
+        setError(
+          t("sagi.startFailed", { error: err instanceof Error ? err.message : String(err) })
+        );
+      } finally {
+        setStarting(false);
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [chat, starting, t, onLocal]
+  );
+
+  // New chat: the old one's session is stopped, not left running unseen —
+  // asking first only while it is still writing a reply.
+  const newChat = async () => {
+    if (chat) {
+      if (
+        busy &&
+        !(await confirmDialog({
+          title: t("sagi.chat.endTitle"),
+          message: t("sagi.chat.endBody"),
+          confirmLabel: t("sagi.chat.endConfirm"),
+          destructive: true,
+        }))
+      )
+        return;
+      try {
+        await api.run.kill(chat.runId, { archive: true });
+      } catch (err) {
+        toast.error(err);
+        return;
+      }
+    }
+    remember(null);
+    setLocal([]);
+    setPending(null);
+    setError(null);
+  };
+
+  const submit = (e?: FormEvent) => {
+    e?.preventDefault();
+    if (!draft.trim()) return;
+    const text = draft;
+    setDraft("");
+    void send(text);
+  };
+
+  const toolLabel = chat?.tool ?? petChatTool() ?? "claude";
+  const empty = lines.length === 0 && !pending;
+
+  return (
+    <div
+      className="pet-chat flex h-[30rem] max-h-[calc(100vh-6rem)] w-80 flex-col overflow-hidden rounded-3xl border border-border-light shadow-2xl animate-slide-up"
+      role="dialog"
+      aria-label={t("sagi.chat.label", { name })}
+    >
+      {/* header */}
+      <div className="pet-chat-head flex items-center gap-1 px-2 py-2">
+        <span className="pl-1.5 text-base leading-none" aria-hidden>
+          🐾
+        </span>
+        <div className="min-w-0 flex-1 px-1">
+          {title ?? <div className="truncate text-sm font-semibold text-fg-primary">{name}</div>}
+          <div className="flex items-center gap-1 text-[10px] uppercase tracking-wider text-fg-muted">
+            <span
+              className={`inline-block h-1.5 w-1.5 rounded-full ${
+                busy
+                  ? "animate-pulse bg-status-warning"
+                  : chat
+                    ? "bg-status-success"
+                    : "bg-fg-muted"
+              }`}
+              aria-hidden
+            />
+            {busy ? t("sagi.chat.typing") : toolLabel}
+          </div>
+        </div>
+        {headerActions}
+        {chat && (
+          <IconButton
+            label={t("sagi.chat.openWorkspace")}
+            onClick={() => onOpenWorkspace(chat.laneId, chat.runId)}
+          >
+            <ExternalLink size={15} />
+          </IconButton>
+        )}
+        <IconButton
+          label={t("sagi.chat.new")}
+          onClick={() => void newChat()}
+          disabled={(!chat && !local.length) || starting}
+        >
+          <SquarePen size={15} />
+        </IconButton>
+        <IconButton label={t("sagi.chat.close", { name })} onClick={onClose}>
+          <X size={16} />
+        </IconButton>
+      </div>
+
+      {info}
+
+      {/* conversation */}
+      <div ref={listRef} className="flex-1 space-y-2 overflow-y-auto px-3 py-3">
+        {empty && (
+          <div className="flex h-full flex-col items-center justify-center gap-2 px-4 text-center">
+            <span className="text-3xl" aria-hidden>
+              🐾
+            </span>
+            <p className="text-sm font-medium text-fg-primary">
+              {t("sagi.chat.emptyTitle", { name })}
+            </p>
+            <p className="text-xs text-fg-muted">{t("sagi.chat.emptyHint", { tool: toolLabel })}</p>
+          </div>
+        )}
+        {lines.map((l) =>
+          l.role === "tools" ? (
+            <div key={l.key} className="flex justify-start">
+              <span className="pet-chat-tools inline-flex max-w-[85%] items-center gap-1 truncate rounded-full px-2 py-0.5 text-[10px] text-fg-muted">
+                <Wrench size={10} className="shrink-0" aria-hidden />
+                <span className="truncate">{toolSummary(l.names)}</span>
+              </span>
+            </div>
+          ) : l.role === "user" ? (
+            <div key={l.key} className="flex justify-end">
+              <div className="max-w-[85%] whitespace-pre-wrap break-words rounded-2xl rounded-br-md bg-accent-solid px-3 py-2 text-sm text-white shadow-sm">
+                {l.text}
+              </div>
+            </div>
+          ) : (
+            <div key={l.key} className="flex justify-start">
+              <div className="pet-chat-reply max-w-[90%] break-words rounded-2xl rounded-bl-md px-3 py-2 text-sm text-fg-primary shadow-sm">
+                <MarkdownContent text={l.text} dense prose />
+              </div>
+            </div>
+          )
+        )}
+        {pending && (
+          <div className="flex justify-end">
+            <div className="max-w-[85%] whitespace-pre-wrap break-words rounded-2xl rounded-br-md bg-accent-solid px-3 py-2 text-sm text-white opacity-70 shadow-sm">
+              {pending}
+            </div>
+          </div>
+        )}
+        {busy && !menu && (
+          <div className="flex justify-start" aria-label={t("sagi.chat.typing")}>
+            <div className="pet-chat-reply flex gap-1 rounded-2xl rounded-bl-md px-3 py-3 shadow-sm">
+              <span className="pet-chat-dot" />
+              <span className="pet-chat-dot" />
+              <span className="pet-chat-dot" />
+            </div>
+          </div>
+        )}
+        {starting && (
+          <p className="flex items-center justify-center gap-1.5 text-[11px] text-fg-muted">
+            <Loader2 size={12} className="animate-spin" aria-hidden />
+            {t("sagi.chat.starting", { tool: toolLabel })}
+          </p>
+        )}
+        {chat && !sessionId && !starting && (
+          <p className="text-center text-[11px] text-fg-muted">{t("sagi.chat.notStarted")}</p>
+        )}
+      </div>
+
+      {error && (
+        <p className="mx-3 mb-1 rounded-lg bg-status-danger/10 px-2 py-1 text-[11px] text-status-danger">
+          {error}
+        </p>
+      )}
+
+      {/* prompt, or the question the CLI asks */}
+      <div className="pet-chat-foot px-2.5 py-2.5">
+        {menu && chat ? (
+          <div className="max-h-56 overflow-y-auto">
+            <PaneMenuCard
+              menu={menu}
+              onChoose={(i) => {
+                if (chooseRunOption(chat.runId, menu, i)) setMenu(null);
+                else setError(t("sagi.chat.notSent"));
+              }}
+              onAnswer={(text) => {
+                if (answerRunMenu(chat.runId, menu, text)) setMenu(null);
+                else setError(t("sagi.chat.notSent"));
+              }}
+              onCancel={() => {
+                if (interruptRun(chat.runId)) setMenu(null);
+                else setError(t("sagi.chat.notSent"));
+              }}
+            />
+          </div>
+        ) : (
+          <form onSubmit={submit} className="flex items-end gap-1.5">
+            <textarea
+              rows={1}
+              autoFocus
+              className="max-h-28 min-h-[2.25rem] flex-1 resize-none rounded-2xl border border-border bg-surface-1 px-3.5 py-2 text-sm text-fg-primary placeholder-fg-muted focus:border-accent focus:outline-none focus:ring-1 focus:ring-accent/30"
+              placeholder={t("sagi.chat.placeholder", { name })}
+              aria-label={t("sagi.chat.placeholder", { name })}
+              value={draft}
+              onChange={(e) => setDraft(e.target.value)}
+              onKeyDown={(e) => {
+                if (isSubmitEnter(e) && !e.shiftKey) {
+                  e.preventDefault();
+                  submit();
+                } else if (e.key === "Escape") {
+                  e.stopPropagation();
+                  e.nativeEvent.stopImmediatePropagation();
+                  onClose();
+                }
+              }}
+            />
+            <button
+              type="submit"
+              disabled={!draft.trim() || starting}
+              className="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-accent-solid text-white shadow-sm transition-opacity hover:opacity-90 disabled:opacity-40"
+              aria-label={t("sagi.panel.send")}
+            >
+              <ArrowUp size={16} />
+            </button>
+          </form>
+        )}
+      </div>
+
+      {/* The chat's pane, attached off-screen: the only way a follow-up or a
+          menu answer reaches it. A real size, so tmux does not shrink the pane. */}
+      {chat && (
+        <div className="pet-chat-term" aria-hidden>
+          <TerminalView
+            runId={chat.runId}
+            wsBaseUrl={window.location.origin.replace(/^http/, "ws")}
+            autoFocus={false}
+            // The pane ended: the conversation stays on screen, the next
+            // message starts a new session.
+            onExit={() => {
+              writePetChat(null);
+              setChat(null);
+            }}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+function IconButton({
+  label,
+  onClick,
+  disabled,
+  children,
+}: {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      className="rounded-full p-1.5 text-fg-muted transition-colors hover:bg-surface-4 hover:text-fg-primary disabled:cursor-not-allowed disabled:opacity-40"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={label}
+      title={label}
+    >
+      {children}
+    </button>
+  );
+}
@@ -0,0 +1,278 @@
+/**
+ * @file PetMenu.tsx
+ * @description The mascot's right-click menu: hide it, size it, choose the
+ * pet it wears — Sagi, a featured pet (downloaded from codex-pets.net into
+ * this install on the first pick, `POST /api/pets/featured/:id`), or one of
+ * your own (deletable) — upload an image or import a `.codex-pet.zip`, browse
+ * codex-pets.net for more, and open the Sagi settings. The choice and the size
+ * are viewer preferences (`prefs.ts`); the pets themselves live on the server
+ * (`server/lib/pets.js`); the list and its actions are `usePets`, shared
+ * with Settings → Appearance.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  Check,
+  ChevronDown,
+  ChevronRight,
+  Download,
+  EyeOff,
+  ExternalLink,
+  Loader2,
+  PackageOpen,
+  Settings2,
+  Trash2,
+  Upload,
+} from "lucide-react";
+import { PET_SIZE, sagiPrefs, type PetChoice } from "./prefs";
+import { usePets } from "./usePets";
+import { usePermissions } from "../AuthGate";
+import { toast } from "../../lib/toast";
+
+const ITEM =
+  "flex w-full items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-sm text-fg-secondary hover:bg-surface-4 hover:text-fg-primary disabled:opacity-50";
+
+export function PetMenu({
+  pet,
+  size,
+  onClose,
+  onSettings,
+}: {
+  pet: PetChoice;
+  size: number;
+  onClose: () => void;
+  onSettings: () => void;
+}) {
+  const { t } = useTranslation("settings");
+  const ref = useRef<HTMLDivElement>(null);
+  const imageInput = useRef<HTMLInputElement>(null);
+  const bundleInput = useRef<HTMLInputElement>(null);
+  const [choosing, setChoosing] = useState(false);
+  const { list, own, installed, busy, error, wear, install, add, remove } = usePets();
+  // Adding or deleting a pet changes the whole install: an admin's.
+  const { isAdmin } = usePermissions();
+
+  // Closes on a press outside the menu, or Escape.
+  useEffect(() => {
+    const onDown = (e: MouseEvent) => {
+      if (!ref.current?.contains(e.target as Node)) onClose();
+    };
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
+    document.addEventListener("mousedown", onDown);
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("mousedown", onDown);
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [onClose]);
+
+  const addFile = (file: File | undefined, bundle: boolean) => file && void add(file, bundle);
+  const mark = (id: string) =>
+    pet.id === id ? <Check className="ml-auto h-3.5 w-3.5 shrink-0 text-accent" /> : null;
+
+  return (
+    <div
+      ref={ref}
+      role="menu"
+      data-testid="pet-menu"
+      className="w-72 rounded-xl border border-border bg-surface-2 p-1.5 text-sm shadow-lg"
+    >
+      <div className="px-2.5 pb-1 pt-0.5 text-xs font-medium text-fg-muted">
+        {t("sagi.pet.title")}
+      </div>
+      <button
+        type="button"
+        role="menuitem"
+        className={ITEM}
+        onClick={() => {
+          sagiPrefs.setEnabled(false);
+          toast.info(t("sagi.pet.hiddenToast"));
+          onClose();
+        }}
+      >
+        <EyeOff className="h-4 w-4" />
+        {t("sagi.pet.hide")}
+      </button>
+      <label className="block px-2.5 py-1.5">
+        <span className="flex items-center justify-between text-sm text-fg-secondary">
+          {t("sagi.pet.size")}
+          <span className="tabular-nums text-xs text-fg-muted">{size}px</span>
+        </span>
+        <input
+          type="range"
+          data-testid="pet-size"
+          min={PET_SIZE.min}
+          max={PET_SIZE.max}
+          value={size}
+          onChange={(e) => sagiPrefs.setSize(Number(e.target.value))}
+          className="mt-1 w-full accent-[rgb(var(--accent))]"
+        />
+      </label>
+      <div className="my-1.5 border-t border-border" />
+      <button
+        type="button"
+        role="menuitem"
+        aria-expanded={choosing}
+        data-testid="pet-choose"
+        className={ITEM}
+        onClick={() => setChoosing((v) => !v)}
+      >
+        {choosing ? <ChevronDown className="h-4 w-4" /> : <ChevronRight className="h-4 w-4" />}
+        {t("sagi.pet.choose")}
+      </button>
+      {choosing && (
+        <div className="max-h-80 overflow-y-auto pl-2">
+          <button
+            type="button"
+            role="menuitemradio"
+            aria-checked={pet.id === "sagi"}
+            className={ITEM}
+            onClick={() => sagiPrefs.setPet({ id: "sagi" })}
+          >
+            Sagi
+            {mark("sagi")}
+          </button>
+          {list?.featured.map((f) => {
+            const have = installed.get(f.id);
+            if (!have && !isAdmin) return null;
+            return (
+              <button
+                key={f.id}
+                type="button"
+                role="menuitemradio"
+                aria-checked={!!have && pet.id === have.id}
+                data-testid={`pet-featured-${f.id}`}
+                disabled={busy !== null}
+                title={t("sagi.pet.featuredBy", { by: f.by })}
+                className={ITEM}
+                onClick={() => (have ? wear(have) : void install(f.id))}
+              >
+                <span className="min-w-0 truncate">{f.displayName}</span>
+                {busy === f.id ? (
+                  <Loader2 className="ml-auto h-3.5 w-3.5 shrink-0 animate-spin" />
+                ) : have ? (
+                  mark(have.id)
+                ) : (
+                  <Download
+                    aria-label={t("sagi.pet.download")}
+                    className="ml-auto h-3.5 w-3.5 shrink-0 text-fg-muted"
+                  />
+                )}
+              </button>
+            );
+          })}
+          {own.length > 0 && <div className="my-1.5 border-t border-border" />}
+          {own.map((p) => (
+            <div key={p.id} className="group flex items-center">
+              <button
+                type="button"
+                role="menuitemradio"
+                aria-checked={pet.id === p.id}
+                data-testid={`pet-own-${p.id}`}
+                className={ITEM}
+                onClick={() => wear(p)}
+              >
+                <span className="min-w-0 truncate">{p.displayName}</span>
+                {mark(p.id)}
+              </button>
+              {isAdmin && (
+                <button
+                  type="button"
+                  data-testid={`pet-delete-${p.id}`}
+                  aria-label={t("sagi.pet.delete", { name: p.displayName })}
+                  title={t("sagi.pet.delete", { name: p.displayName })}
+                  disabled={busy !== null}
+                  onClick={() => void remove(p)}
+                  className="rounded p-1 text-fg-muted hover:bg-surface-4 hover:text-status-danger"
+                >
+                  <Trash2 className="h-3.5 w-3.5" />
+                </button>
+              )}
+            </div>
+          ))}
+          <div className="my-1.5 border-t border-border" />
+          {isAdmin && (
+            <>
+              <button
+                type="button"
+                role="menuitem"
+                disabled={busy !== null}
+                className={ITEM}
+                onClick={() => imageInput.current?.click()}
+              >
+                {busy === "image" ? (
+                  <Loader2 className="h-4 w-4 animate-spin" />
+                ) : (
+                  <Upload className="h-4 w-4" />
+                )}
+                {t("sagi.pet.upload")}
+              </button>
+              <button
+                type="button"
+                role="menuitem"
+                disabled={busy !== null}
+                className={ITEM}
+                onClick={() => bundleInput.current?.click()}
+              >
+                {busy === "bundle" ? (
+                  <Loader2 className="h-4 w-4 animate-spin" />
+                ) : (
+                  <PackageOpen className="h-4 w-4" />
+                )}
+                {t("sagi.pet.import")}
+              </button>
+            </>
+          )}
+          <a
+            href="https://codex-pets.net/"
+            target="_blank"
+            rel="noreferrer noopener"
+            className={`${ITEM} !text-fg-muted`}
+          >
+            <ExternalLink className="h-4 w-4" />
+            {t("sagi.pet.browse")}
+          </a>
+        </div>
+      )}
+      <input
+        ref={imageInput}
+        type="file"
+        hidden
+        data-testid="pet-image-input"
+        accept="image/png,image/jpeg,image/gif,image/webp"
+        onChange={(e) => {
+          addFile(e.target.files?.[0], false);
+          e.target.value = "";
+        }}
+      />
+      <input
+        ref={bundleInput}
+        type="file"
+        hidden
+        data-testid="pet-bundle-input"
+        accept=".zip,application/zip"
+        onChange={(e) => {
+          addFile(e.target.files?.[0], true);
+          e.target.value = "";
+        }}
+      />
+      {error && (
+        <p role="alert" className="px-2.5 py-1 text-xs text-status-danger">
+          {error}
+        </p>
+      )}
+      <div className="my-1.5 border-t border-border" />
+      <button
+        type="button"
+        role="menuitem"
+        className={`${ITEM} !text-fg-muted`}
+        onClick={onSettings}
+      >
+        <Settings2 className="h-4 w-4" />
+        {t("sagi.pet.settings")}
+      </button>
+    </div>
+  );
+}
@@ -0,0 +1,183 @@
+/**
+ * @file PetSprite.tsx
+ * @description The mascot wearing a custom pet (`/api/pets`). A Codex pet is
+ * a spritesheet of 192×208 frames, 8 columns wide: 9 rows (v1, 1536×1872),
+ * one per animation state (idle, run right, run left, waving, jumping, failed,
+ * waiting, running, review), or 11 (v2, 1536×2288), whose rows 9–10 are 16
+ * gaze poses. The sprite plays the row of Sagi's mood at Codex's own frame
+ * timings; a moment (waving, jumping, failed, review) plays three times and
+ * settles into idle, a condition loops. An `action` (dragged left/right,
+ * hovered) plays the run-left/run-right or waving row over the mood's, like
+ * Codex's own pet; a `moment` (a new session waves, a finish jumps, an error
+ * fails, a wait waits, a new subagent reviews — `useSagiBrain`) plays its row
+ * over the mood's, under the action; a v2 pet at idle holds the gaze pose `gaze` names. An
+ * uploaded image is shown still and bobs with the same `data-mood` CSS as
+ * Sagi. Reduced motion holds the row's first frame. A sprite that fails to
+ * load (deleted from another browser) calls `onBroken`, so the mascot falls
+ * back to Sagi instead of an empty box.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useState } from "react";
+import { api } from "../../lib/api";
+import type { Mood, PetMoment } from "./brain";
+
+const CELL = { w: 192, h: 208 };
+const COLS = 8;
+/** `n` frames of `step` ms, the last one `last` ms. */
+const frames = (n: number, step: number, last: number) =>
+  Array.from({ length: n }, (_, i) => (i === n - 1 ? last : step));
+/** Per row, each frame's ms: Codex's own table (codex-rs/tui/src/pets/model.rs).
+ *  Idle is the pace the pets are drawn at; Codex plays it 6× slower, which is
+ *  how a sleeping pet breathes here. */
+const DURATIONS = [
+  [280, 110, 110, 140, 140, 320], // idle
+  frames(8, 120, 220), // run right
+  frames(8, 120, 220), // run left
+  frames(4, 140, 280), // waving
+  frames(5, 140, 280), // jumping
+  frames(8, 140, 240), // failed
+  frames(6, 150, 260), // waiting
+  frames(6, 120, 220), // running (working)
+  frames(6, 150, 280), // review
+];
+const SLEEP_SLOWDOWN = 6;
+/** Rows that play three times and settle into idle; the others loop. */
+const MOMENTS = new Set([3, 4, 5, 8]);
+/** v2 only: 16 gaze poses, 22.5° apart clockwise from straight up. */
+const GAZE_ROW = 9;
+/** Which row plays for each mood. */
+const ROW: Record<Mood, number> = {
+  idle: 0,
+  sleeping: 0,
+  thinking: 7, // running — an agent is working
+  watching: 8, // review
+  happy: 4, // jumping
+  stuck: 6, // waiting — for the user
+  worried: 5, // failed
+  disconnected: 5,
+};
+/** What the user is doing to the pet, which outranks its mood. */
+export type PetAction = "run-left" | "run-right" | "wave";
+const ACTION_ROW: Record<PetAction, number> = { "run-right": 1, "run-left": 2, wave: 3 };
+/** A moment's row: wave, jump, failed, waiting, review. It outranks the mood,
+ *  and the user's own action outranks it. */
+const MOMENT_ROW: Record<PetMoment, number> = { wave: 3, jump: 4, fail: 5, wait: 6, review: 8 };
+/** Loops of a row before the sprite rests on its first frame. */
+const SPRITE_LOOPS = 4;
+
+export function PetSprite({
+  id,
+  kind,
+  mood,
+  action,
+  moment,
+  gaze,
+  size,
+  reducedMotion,
+  onBroken,
+}: {
+  id: string;
+  kind: "codex" | "image";
+  mood: Mood;
+  action?: PetAction | null;
+  moment?: PetMoment | null;
+  /** Gaze pose 0–15 (0 = up, clockwise), or none. Only a v2 sheet has them. */
+  gaze?: number | null;
+  size: number;
+  reducedMotion: boolean;
+  onBroken: () => void;
+}) {
+  const url = api.pets.spriteUrl(id);
+  const row = action ? ACTION_ROW[action] : moment ? MOMENT_ROW[moment] : (ROW[mood] ?? 0);
+  const sleeping = !action && !moment && mood === "sleeping";
+  // The cell on show, tagged with the row it was played for: a cell left over
+  // from the previous row (say column 7 of a run) is never drawn on the next.
+  const [cell, setCell] = useState({ of: row, row, col: 0 });
+  const [rows, setRows] = useState(9);
+
+  useEffect(() => {
+    setCell({ of: row, row, col: 0 });
+    if (kind !== "codex" || reducedMotion) return;
+    const play = (r: number, slow = 1) =>
+      (DURATIONS[r] ?? [200]).map((ms, col) => ({ of: row, row: r, col, ms: ms * slow }));
+    const own = play(row, sleeping ? SLEEP_SLOWDOWN : 1);
+    let list = MOMENTS.has(row) ? [...own, ...own, ...own] : own;
+    let i = 0;
+    let loops = 0;
+    let timer = 0;
+    // `i` always indexes `list`: it wraps at its end. A few loops, then the
+    // first frame rests — a sprite that never stops re-paints the page several
+    // times a second for as long as it is open; a new mood or action plays again.
+    const tick = () => {
+      timer = window.setTimeout(() => {
+        if (++i === list.length) {
+          i = 0;
+          if (MOMENTS.has(row)) list = play(0);
+          if (++loops >= SPRITE_LOOPS) return setCell(list[0]!);
+        }
+        setCell(list[i]!);
+        tick();
+      }, list[i]!.ms);
+    };
+    tick();
+    return () => window.clearTimeout(timer);
+  }, [kind, row, sleeping, reducedMotion]);
+
+  // A background image reports no error of its own: probe it once.
+  useEffect(() => {
+    if (kind !== "codex") return;
+    // It also tells a v2 sheet (11 rows) from a v1 (9).
+    const probe = new Image();
+    probe.onload = () => setRows(Math.round(probe.naturalHeight / CELL.h) || 9);
+    probe.onerror = onBroken;
+    probe.src = url;
+    return () => {
+      probe.onload = null;
+      probe.onerror = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [url, kind]);
+
+  if (kind === "image") {
+    return (
+      <img
+        src={url}
+        alt=""
+        data-mood={mood}
+        data-moment={moment ?? undefined}
+        className="sagi-pet-image"
+        width={size}
+        height={size}
+        draggable={false}
+        onError={onBroken}
+        style={{ width: size, height: size, objectFit: "contain" }}
+      />
+    );
+  }
+  const pose =
+    gaze != null && rows > GAZE_ROW && !action && !moment && mood === "idle" ? gaze : null;
+  const shown =
+    pose != null
+      ? { row: GAZE_ROW + Math.floor(pose / COLS), col: pose % COLS }
+      : cell.of === row
+        ? cell
+        : { row, col: 0 };
+  const scale = size / CELL.h;
+  return (
+    <div
+      data-testid="pet-sprite"
+      data-row={shown.row}
+      aria-hidden
+      style={{
+        width: Math.round(CELL.w * scale),
+        height: size,
+        margin: "0 auto",
+        backgroundImage: `url("${url}")`,
+        backgroundRepeat: "no-repeat",
+        backgroundSize: `${COLS * CELL.w * scale}px ${rows * CELL.h * scale}px`,
+        backgroundPosition: `${-shown.col * CELL.w * scale}px ${-shown.row * CELL.h * scale}px`,
+      }}
+    />
+  );
+}
@@ -1,15 +1,25 @@
 /**
 * @file Sagi.tsx
- * @description Floating mascot companion shell. Mounts once (next to UpdateNotifier
- *   in Layout) so it persists across routes and shares the single WebSocket.
- *   Owns the open/closed panel state, the ⌘B / Esc shortcuts, reduced-motion
+ * @description Floating mascot companion shell. Mounted once by `SagiMount` (next
+ *   to UpdateNotifier in Layout), which loads this chunk only while the mascot is
+ *   enabled; `Sagi` gates on the same preference itself, and the body (brain,
+ *   tick, WS reducer) runs only while it is on. Persists across routes and
+ *   shares the single WebSocket.
+ *   Clicking the pet opens its chat window (`PetChat`), which is its whole UI:
+ *   the status strip (`SagiInfo`) sits on top, a question the pet can answer
+ *   itself is answered there, anything else goes to the AI.
+ *   Owns the open/closed chat state, the ⌘B / Esc shortcuts, reduced-motion
 *   detection, and route navigation. Reactive personality + status/Ask come
 *   from useSagiBrain; the avatar is draggable (AssistiveTouch-style) via
- *   useSagiPosition, and the bubble/panel render in a self-clamping flyout so
+ *   useSagiPosition (a v2 Codex pet also looks toward the pointer), and the
+ *   bubble/panel render in a self-clamping flyout so
 *   they never spill off any screen edge regardless of where the mascot is docked.
 *
- *   The "do the job" path reuses the existing Run page: unmatched Ask queries
- *   deep-link to /run?prompt=…&autostart=1 - no new LLM backend.
+ *   The "do the job" path: an unmatched question is the chat's — it starts a
+ *   session of the default AI tool in the "Sagi" workspace; a default tool the
+ *   chat cannot read back starts there and its session view opens
+ *   (`/workspace?lane=<id>&run=<runId>`) — no new LLM backend. ⌘B/Ctrl+B is taken only while the mascot is shown and focus is not
+ *   in an editable field (a terminal's Ctrl+B is tmux's prefix).
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
 /* =============================================================================
@@ -32,7 +42,7 @@
 * ## Internal dependencies
 * - `./SagiAvatar`
 * - `./SpeechBubble`
- * - `./SagiPanel`
+ * - `./SagiInfo`
 * - `./useSagiBrain`
 * - `./useSagiPosition`
 * - `./intents`
@@ -70,19 +80,48 @@ import {
  type ReactNode,
 } from "react";
 import { useNavigate } from "react-router-dom";
+import { useSettingsHref } from "../../lib/settingsLink";
+import { usePrefersReducedMotion } from "../../hooks/usePrefersReducedMotion";
+import { useTranslation } from "react-i18next";
 import { SagiAvatar } from "./SagiAvatar";
+import { PetSprite } from "./PetSprite";
+import { PetMenu } from "./PetMenu";
 import { SpeechBubble } from "./SpeechBubble";
-import { SagiPanel } from "./SagiPanel";
+import { PetNameButton, SagiInfo } from "./SagiInfo";
 import { useSagiBrain } from "./useSagiBrain";
-import { useSagiPosition, SAGI_SIZE } from "./useSagiPosition";
+import { useSagiPosition } from "./useSagiPosition";
+import { useSagiEnabled } from "./SagiMount";
 import { matchIntent } from "./intents";
-import { sagiPrefs } from "./prefs";
+import { petName, sagiPrefs } from "./prefs";
+import type { SagiSubject } from "./brain";
 import { api } from "../../lib/api";
+import { readDefaultTool } from "../../lib/sessionDefaults";
+import { startInFreeTabDetailed } from "../lanes/startSession";
+import { workspaceHref } from "../SessionRowMenu";
+import { Heart } from "lucide-react";
+import { PetChat, petChatTool, type PetLocalReply } from "./PetChat";
+
+// Stroking: this many left/right turns of the pointer over the pet, within
+// STROKE_MS and with no button held, is a pat; then a pause before the next.
+const STROKE_TURNS = 4;
+const STROKE_MS = 1200;
+const STROKE_COOLDOWN_MS = 1500;
 import "./sagi.css";

 const FLYOUT_GAP = 10; // px between avatar and flyout
 const VIEWPORT_MARGIN = 12; // min gap from any screen edge

+/** True while focus sits where typing happens (an input, a terminal's textarea). */
+function isEditable(el: EventTarget | null): boolean {
+  if (!(el instanceof HTMLElement)) return false;
+  return (
+    el.isContentEditable ||
+    el.tagName === "INPUT" ||
+    el.tagName === "TEXTAREA" ||
+    el.tagName === "SELECT"
+  );
+}
+
 interface Anchor {
  left: number;
  top: number;
@@ -92,29 +131,28 @@ interface Anchor {
  dragging: boolean;
 }

-function usePrefersReducedMotion(): boolean {
-  const [reduced, setReduced] = useState(
-    () =>
-      typeof window !== "undefined" &&
-      window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
-  );
-  useEffect(() => {
-    const mq = window.matchMedia?.("(prefers-reduced-motion: reduce)");
-    if (!mq) return;
-    const onChange = () => setReduced(mq.matches);
-    mq.addEventListener?.("change", onChange);
-    return () => mq.removeEventListener?.("change", onChange);
-  }, []);
-  return reduced;
-}
-
 /**
 * Fixed-position wrapper that places its content next to the avatar and clamps
 * it inside the viewport. It measures itself (and re-measures on content/size
 * changes via ResizeObserver) so a tall panel near a screen edge slides fully
 * into view instead of being cropped.
 */
-function SagiFlyout({ anchor, children }: { anchor: Anchor; children: ReactNode }) {
+/**
+ * `front`: above the mascot itself — the pet menu, which may overlap it.
+ * `beside`: at the mascot's side instead of above it — the chat window, on the
+ * screen side away from the edge it docks to, its bottom level with the pet's.
+ */
+function SagiFlyout({
+  anchor,
+  children,
+  front = false,
+  beside = false,
+}: {
+  anchor: Anchor;
+  children: ReactNode;
+  front?: boolean;
+  beside?: boolean;
+}) {
  const ref = useRef<HTMLDivElement>(null);
  const [style, setStyle] = useState<CSSProperties>({ visibility: "hidden" });

@@ -126,6 +164,18 @@ function SagiFlyout({ anchor, children }: { anchor: Anchor; children: ReactNode
    const vw = window.innerWidth;
    const vh = window.innerHeight;

+    if (beside) {
+      let left =
+        anchor.side === "left"
+          ? anchor.left + anchor.size + FLYOUT_GAP
+          : anchor.left - w - FLYOUT_GAP;
+      left = Math.min(vw - w - VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, left));
+      let top = anchor.top + anchor.size - h;
+      top = Math.min(vh - h - VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, top));
+      setStyle({ left, top, visibility: "visible" });
+      return;
+    }
+
    // Horizontal: hug the avatar's docked edge, then clamp on-screen.
    let left = anchor.side === "left" ? anchor.left : anchor.left + anchor.size - w;
    left = Math.min(vw - w - VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, left));
@@ -138,7 +188,7 @@ function SagiFlyout({ anchor, children }: { anchor: Anchor; children: ReactNode
    top = Math.min(vh - h - VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, top));

    setStyle({ left, top, visibility: "visible" });
-  }, [anchor.left, anchor.top, anchor.size, anchor.side, anchor.openUp]);
+  }, [anchor.left, anchor.top, anchor.size, anchor.side, anchor.openUp, beside]);

  useLayoutEffect(() => {
    place();
@@ -160,6 +210,7 @@ function SagiFlyout({ anchor, children }: { anchor: Anchor; children: ReactNode
      // Mirrors the avatar button: eased left/top so the flyout glides along
      // with the mascot when it snaps to an edge, 1:1 (no easing) mid-drag.
      data-dragging={anchor.dragging ? "1" : "0"}
+      data-front={front ? "1" : undefined}
      style={style}
    >
      {children}
@@ -167,21 +218,66 @@ function SagiFlyout({ anchor, children }: { anchor: Anchor; children: ReactNode
  );
 }

+/** Renders nothing — and runs no hook below — while the mascot is disabled. */
 export function Sagi() {
-  const [enabled, setEnabled] = useState(() => sagiPrefs.getEnabled());
+  return useSagiEnabled() ? <SagiBody /> : null;
+}
+
+function SagiBody() {
+  const { t } = useTranslation("settings");
+  const [pet, setPet] = useState(() => sagiPrefs.getPet());
+  // The name it goes by: the user's nickname, the pet's own, else Sagi.
+  const [name, setName] = useState(() => petName(sagiPrefs.getPet()));
+  const [size, setSize] = useState(() => sagiPrefs.getSize());
+  // The chat window (PetChat.tsx): the pet's whole UI.
  const [open, setOpen] = useState(false);
+  // The right-click pet menu (`PetMenu.tsx`).
+  const [menu, setMenu] = useState(false);
+  const [hover, setHover] = useState(false);
  const reducedMotion = usePrefersReducedMotion();
  const navigate = useNavigate();
+  const href = useSettingsHref();
  const brain = useSagiBrain();
-  const place = useSagiPosition();
+  const place = useSagiPosition(size);

-  // Keep enabled in sync with Settings / other tabs.
-  useEffect(() => sagiPrefs.subscribe(() => setEnabled(sagiPrefs.getEnabled())), []);
+  // Keep the pet and its size in sync with Settings / other tabs (enabled is
+  // the `Sagi` gate's: it unmounts this body when the mascot is turned off).
+  useEffect(
+    () =>
+      sagiPrefs.subscribe(() => {
+        setPet(sagiPrefs.getPet());
+        setName(petName(sagiPrefs.getPet()));
+        setSize(sagiPrefs.getSize());
+      }),
+    []
+  );

-  // ⌘B / Ctrl+B toggles the panel; Esc closes it.
+  // A pet worn before names rode along with the choice: look its name up once.
+  const petId = pet.id;
+  const unnamed = "kind" in pet && !pet.name;
+  useEffect(() => {
+    if (!unnamed) return;
+    let live = true;
+    api.pets
+      .list()
+      .then((list) => {
+        const found = list.pets.find((p) => p.id === petId);
+        const cur = sagiPrefs.getPet();
+        if (live && found && cur.id === petId && "kind" in cur)
+          sagiPrefs.setPet({ ...cur, name: found.displayName });
+      })
+      .catch(() => undefined);
+    return () => {
+      live = false;
+    };
+  }, [petId, unnamed]);
+
+  // ⌘B / Ctrl+B toggles the panel; Esc closes it. Only while the mascot is
+  // shown, and never from an editable field, where Ctrl+B belongs to the field.
  useEffect(() => {
    const onKey = (e: KeyboardEvent) => {
      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "b") {
+        if (isEditable(e.target) || isEditable(document.activeElement)) return;
        e.preventDefault();
        setOpen((v) => !v);
      } else if (e.key === "Escape") {
@@ -192,6 +288,32 @@ export function Sagi() {
    return () => window.removeEventListener("keydown", onKey);
  }, []);

+  // A v2 pet at idle looks toward the pointer: one of 16 poses by the
+  // pointer's angle around it (0 = up, clockwise), dropped once it rests.
+  // ponytail: rest after 2 s is a guess; Codex Desktop's own rule is not public.
+  const btn = useRef<HTMLButtonElement>(null);
+  const [gaze, setGaze] = useState<number | null>(null);
+  const wearsSheet = "kind" in pet && pet.kind === "codex";
+  useEffect(() => {
+    if (!wearsSheet || reducedMotion) return;
+    let rest = 0;
+    const onMove = (e: PointerEvent) => {
+      const r = btn.current?.getBoundingClientRect();
+      if (!r) return;
+      const deg =
+        (Math.atan2(e.clientX - (r.left + r.width / 2), r.top + r.height / 2 - e.clientY) * 180) /
+        Math.PI;
+      setGaze(Math.round((deg + 360) / 22.5) % 16);
+      window.clearTimeout(rest);
+      rest = window.setTimeout(() => setGaze(null), 2000);
+    };
+    window.addEventListener("pointermove", onMove);
+    return () => {
+      window.removeEventListener("pointermove", onMove);
+      window.clearTimeout(rest);
+    };
+  }, [wearsSheet, reducedMotion]);
+
  const onNavigate = useCallback(
    (route: string) => {
      navigate(route);
@@ -200,41 +322,83 @@ export function Sagi() {
    [navigate]
  );

-  const onAsk = useCallback(
-    (query: string): string | null => {
-      const result = matchIntent(query, brain.status);
-      if (result.kind === "answer") return result.text;
-      // Handoff: ensure the "Sagi" lane exists for this dashboard, spawn a
-      // fresh claude session in it carrying the user's prompt as its first
-      // message, then jump to the Run page so the live pane is observable.
-      // Fire-and-forget — the panel already clears its composer on null and
-      // closes; errors surface as an answer instead of silently swallowing.
+  // A session a bubble or the panel names: its live pane when a dashboard run
+  // holds it, else its workspace's replay, else its analysis page. Opening
+  // never resumes anything.
+  const openSession = useCallback(
+    (s: SagiSubject) => {
+      const go = (runs?: Parameters<typeof workspaceHref>[1]) => {
+        navigate(workspaceHref(s, runs) ?? `/sessions/${encodeURIComponent(s.id)}`);
+        brain.dismissBubble();
+        setOpen(false);
+      };
+      api.run
+        .list()
+        .then((r) => go(r.items))
+        .catch(() => go());
+    },
+    [brain, navigate]
+  );
+
+  // Asked by the chat before any session runs.
+  const onLocal = useCallback(
+    (query: string): PetLocalReply => {
+      const result = matchIntent(query, brain.status, { name, attention: brain.attention });
+      if (result.kind === "answer") {
+        if (result.moment) brain.playMoment(result.moment);
+        return { answer: result.text };
+      }
+      // A question the pet cannot answer: the chat starts a session of the
+      // default AI tool and shows it as chat.
+      if (petChatTool()) return null;
+      // A default tool the chat cannot read back (not Claude/Codex): start it
+      // in the "Sagi" workspace and open its pane there, as before.
      const prompt = result.prompt;
      brain.setThinking(true);
      (async () => {
        try {
          const { lane } = await api.lanes.ensure({ title: "Sagi" });
-          await api.run.start({
-            laneId: lane.id,
-            cwd: lane.cwd,
-            initialPrompt: prompt,
-            permissionMode: "acceptEdits",
+          const tool = readDefaultTool();
+          const r = await startInFreeTabDetailed(lane.id, {
+            prompt,
+            ...(tool && tool !== lane.tool ? { tool } : {}),
          });
-          navigate(`/run?laneId=${lane.id}&autostart=1`);
+          navigate(`/workspace?lane=${r.laneId}&run=${encodeURIComponent(r.runId)}`);
          setOpen(false);
        } catch (err) {
          const msg = err instanceof Error ? err.message : String(err);
-          brain.setBubble(`couldn't start that session: ${msg}`);
+          brain.setBubble(t("sagi.startFailed", { error: msg }));
        } finally {
          brain.setThinking(false);
        }
      })();
-      return null;
+      return { handled: true };
    },
-    [brain, navigate]
+    [brain, navigate, t, name]
  );

-  if (!enabled) return null;
+  // Stroke the pet (move the pointer back and forth over it) to pat it.
+  const stroke = useRef({ dir: 0, x: 0, turns: [] as number[], until: 0 });
+  const onStroke = (e: React.PointerEvent) => {
+    if (e.buttons !== 0 || e.pointerType === "touch") return;
+    const s = stroke.current;
+    const now = performance.now();
+    const dx = e.clientX - s.x;
+    s.x = e.clientX;
+    if (Math.abs(dx) < 2 || now < s.until) return;
+    const dir = Math.sign(dx);
+    if (s.dir && dir !== s.dir) {
+      s.turns = [...s.turns.filter((t0) => now - t0 < STROKE_MS), now];
+      if (s.turns.length >= STROKE_TURNS) {
+        s.turns = [];
+        s.until = now + STROKE_COOLDOWN_MS;
+        brain.pat();
+      }
+    }
+    s.dir = dir;
+  };
+
+  const onBusy = useCallback((b: boolean) => brain.setThinking(b), [brain.setThinking]);

  const anchor: Anchor = {
    left: place.left,
@@ -247,50 +411,155 @@ export function Sagi() {

  return (
    <>
-      {/* The panel is too big to drag around, so it hides mid-drag. The bubble
-          does not - it is Sagi talking, and it has to stay by its mouth. */}
-      {!place.dragging && open && (
-        <SagiFlyout anchor={anchor}>
-          <SagiPanel
-            status={brain.status}
-            muted={brain.muted}
-            onToggleMute={brain.toggleMute}
-            onClearAlerts={brain.clearAlerts}
-            onNavigate={onNavigate}
-            onAsk={onAsk}
+      {/* Beside the pet, riding along with it mid-drag too (SagiFlyout follows
+          it 1:1). Closing unmounts it; its chat is remembered, so reopening
+          re-attaches the same session. */}
+      {open && (
+        <SagiFlyout anchor={anchor} beside>
+          <PetChat
+            name={name}
+            title={
+              <PetNameButton
+                name={name}
+                ownName={"kind" in pet ? pet.name || "Sagi" : "Sagi"}
+                nickname={sagiPrefs.getNickname(pet.id)}
+                onRename={(next) => sagiPrefs.setNickname(pet.id, next)}
+              />
+            }
+            headerActions={
+              <button
+                type="button"
+                className="rounded-full p-1.5 text-fg-muted transition-colors hover:bg-surface-4 hover:text-status-danger"
+                onClick={brain.pat}
+                aria-label={t("sagi.panel.pat", { name })}
+                title={t("sagi.panel.pat", { name })}
+              >
+                <Heart size={15} />
+              </button>
+            }
+            info={
+              <SagiInfo
+                attention={brain.attention}
+                onOpenSession={openSession}
+                status={brain.status}
+                muted={brain.muted}
+                onToggleMute={brain.toggleMute}
+                onClearAlerts={brain.clearAlerts}
+                onNavigate={onNavigate}
+                defaultOpen={brain.attention.length > 0}
+              />
+            }
+            onLocal={onLocal}
            onClose={() => setOpen(false)}
+            onOpenWorkspace={(laneId, runId) => {
+              navigate(`/workspace?lane=${laneId}&run=${encodeURIComponent(runId)}`);
+              setOpen(false);
+            }}
+            onBusy={onBusy}
          />
        </SagiFlyout>
      )}

-      {!open && brain.bubble && (
+      {!place.dragging && menu && (
+        <SagiFlyout anchor={anchor} front>
+          <PetMenu
+            pet={pet}
+            size={size}
+            onClose={() => setMenu(false)}
+            onSettings={() => {
+              setMenu(false);
+              navigate(href("appearance#pet"));
+            }}
+          />
+        </SagiFlyout>
+      )}
+
+      {!open && !menu && brain.bubble && (
        <SagiFlyout anchor={anchor}>
-          <SpeechBubble text={brain.bubble} onDismiss={brain.dismissBubble} />
+          <SpeechBubble
+            bubble={brain.bubble}
+            onDismiss={brain.dismissBubble}
+            onOpen={openSession}
+          />
        </SagiFlyout>
      )}

      <button
+        ref={btn}
        className="sagi-avatar-btn"
        data-dragging={place.dragging ? "1" : "0"}
-        style={{ left: place.left, top: place.top, width: SAGI_SIZE, height: SAGI_SIZE }}
+        style={{ left: place.left, top: place.top, width: size, height: size }}
+        onPointerEnter={() => setHover(true)}
+        onPointerLeave={() => setHover(false)}
        onPointerDown={place.onPointerDown}
-        onPointerMove={place.onPointerMove}
+        onPointerMove={(e) => {
+          place.onPointerMove(e);
+          onStroke(e);
+        }}
        onPointerUp={place.onPointerUp}
+        onKeyDown={place.onKeyDown}
        onClick={() => {
          // A drag just ended - swallow the synthetic click so the panel
          // doesn't toggle when the user only repositioned the avatar.
          if (place.consumeDrag()) return;
          setOpen((v) => !v);
        }}
-        aria-label={open ? "Close Sagi" : "Open Sagi companion"}
+        // Right-click: the pet menu (hide, size, choose, upload, import).
+        onContextMenu={(e) => {
+          e.preventDefault();
+          setOpen(false);
+          setMenu(true);
+        }}
+        aria-label={open ? t("sagi.closeAvatar", { name }) : t("sagi.open", { name })}
        aria-expanded={open}
-        title="Sagi - ⌘B · drag to move"
+        title={t("sagi.avatarTitle", { name })}
      >
-        <SagiAvatar mood={brain.mood} reducedMotion={reducedMotion} />
-        {brain.status.errorCount > 0 && (
+        {pet.id === "sagi" || !("kind" in pet) ? (
+          <SagiAvatar
+            mood={brain.mood}
+            moment={reducedMotion ? null : brain.moment?.kind}
+            reducedMotion={reducedMotion}
+            size={size}
+          />
+        ) : (
+          <PetSprite
+            id={pet.id}
+            kind={pet.kind}
+            mood={brain.mood}
+            // Dragged → runs that way; hovered → waves (Codex's pet does both).
+            // A moment (a pat's hop) outranks the hover wave, or stroking the
+            // pet would only ever show it waving.
+            action={place.moving ? `run-${place.moving}` : hover && !brain.moment ? "wave" : null}
+            moment={brain.moment?.kind}
+            gaze={gaze}
+            size={size}
+            reducedMotion={reducedMotion}
+            // Deleted elsewhere, or unreadable: back to Sagi.
+            onBroken={() => sagiPrefs.setPet({ id: "sagi" })}
+          />
+        )}
+        {brain.reaction && (
+          <span key={brain.reaction.key} className="sagi-reaction" aria-live="polite">
+            <span className="sagi-hearts" aria-hidden>
+              <span>💜</span>
+              <span>💗</span>
+              <span>💜</span>
+            </span>
+            <span className="sagi-reaction-text" data-side={place.side}>
+              {brain.reaction.text}
+            </span>
+          </span>
+        )}
+        {brain.status.errorCount > 0 ? (
          <span className="sagi-error-dot" aria-hidden>
            {brain.status.errorCount > 9 ? "9+" : brain.status.errorCount}
          </span>
+        ) : (
+          brain.status.waitingCount > 0 && (
+            <span className="sagi-error-dot" data-kind="waiting" aria-hidden>
+              {brain.status.waitingCount > 9 ? "9+" : brain.status.waitingCount}
+            </span>
+          )
        )}
      </button>
    </>
@@ -36,13 +36,15 @@
 * - `skills/file-headers/` — mandatory `@author` header policy.
 * ============================================================================= */

-import { useEffect, useRef, useState } from "react";
-import type { Mood } from "./brain";
+import { memo, useEffect, useRef } from "react";
+import type { Mood, PetMoment } from "./brain";

 interface SagiAvatarProps {
  mood: Mood;
  reducedMotion: boolean;
  size?: number;
+  /** A one-shot reaction (hop, wiggle, flinch…) played over the mood. */
+  moment?: PetMoment | null;
 }

 const MAX_PUPIL_SHIFT = 36; // px in the 1280-unit path coordinate space
@@ -76,10 +78,22 @@ if (typeof window !== "undefined") {
  });
 }

-export function SagiAvatar({ mood, reducedMotion, size = 68 }: SagiAvatarProps) {
+// The pupil offset is written as CSS variables on the root, never as state, so
+// following the cursor costs no React render.
+function setPupil(el: SVGSVGElement | null, x: number, y: number) {
+  el?.style.setProperty("--sagi-px", `${x}px`);
+  el?.style.setProperty("--sagi-py", `${y}px`);
+}
+
+// memo: Sagi re-renders on every brain tick; the avatar only on mood/size/motion.
+export const SagiAvatar = memo(function SagiAvatar({
+  mood,
+  reducedMotion,
+  size = 68,
+  moment = null,
+}: SagiAvatarProps) {
  const rootRef = useRef<SVGSVGElement | null>(null);
  const rafRef = useRef<number>();
-  const [pupil, setPupil] = useState({ x: 0, y: 0 });

  // Pupils follow the cursor whenever motion is allowed and the eyes are open.
  // (Only `sleeping` closes them by intent; `disconnected` hides the open-eye
@@ -89,7 +103,7 @@ export function SagiAvatar({ mood, reducedMotion, size = 68 }: SagiAvatarProps)

  useEffect(() => {
    if (!tracking) {
-      setPupil({ x: 0, y: 0 });
+      setPupil(rootRef.current, 0, 0);
      return;
    }

@@ -105,7 +119,7 @@ export function SagiAvatar({ mood, reducedMotion, size = 68 }: SagiAvatarProps)
      // Normalize then clamp to the eye socket range.
      const nx = (dx / dist) * Math.min(1, dist / 240);
      const ny = (dy / dist) * Math.min(1, dist / 240);
-      setPupil({ x: nx * MAX_PUPIL_SHIFT, y: ny * MAX_PUPIL_SHIFT });
+      setPupil(el, nx * MAX_PUPIL_SHIFT, ny * MAX_PUPIL_SHIFT);
    };

    // Immediately aim at the last-known cursor (next frame, so layout is ready)
@@ -137,6 +151,7 @@ export function SagiAvatar({ mood, reducedMotion, size = 68 }: SagiAvatarProps)
      ref={rootRef}
      className="sagi-avatar"
      data-mood={mood}
+      data-moment={moment ?? undefined}
      data-reduced={reducedMotion ? "1" : "0"}
      width={size}
      height={size}
@@ -202,7 +217,7 @@ export function SagiAvatar({ mood, reducedMotion, size = 68 }: SagiAvatarProps)
      <g className="sagi-eye sagi-eye-left">
        <g
          className="sagi-eye-track"
-          style={{ transform: `translate(${pupil.x}px, ${pupil.y}px)` }}
+          style={{ transform: "translate(var(--sagi-px, 0px), var(--sagi-py, 0px))" }}
        >
          <g className="sagi-eye-blink">
            <path
@@ -226,7 +241,7 @@ export function SagiAvatar({ mood, reducedMotion, size = 68 }: SagiAvatarProps)
      <g className="sagi-eye sagi-eye-right">
        <g
          className="sagi-eye-track"
-          style={{ transform: `translate(${pupil.x}px, ${pupil.y}px)` }}
+          style={{ transform: "translate(var(--sagi-px, 0px), var(--sagi-py, 0px))" }}
        >
          <g className="sagi-eye-blink">
            <path
@@ -792,4 +807,4 @@ export function SagiAvatar({ mood, reducedMotion, size = 68 }: SagiAvatarProps)
      </g>
    </svg>
  );
-}
+});
@@ -0,0 +1,297 @@
+/**
+ * @file SagiInfo.tsx
+ * @description What the pet knows, shown inside its chat window (`PetChat`):
+ *   the name you rename by clicking it (`PetNameButton`), and a status strip
+ *   (`SagiInfo`) — live / waiting / errored counts and the connection state
+ *   always in sight, and on expanding, the sessions that need the user, by
+ *   name, plus Mute and Clear alerts. Pure presentational: all data and
+ *   behavior are injected by the container (`Sagi.tsx`).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useState } from "react";
+import {
+  AlertTriangle,
+  Bell,
+  BellOff,
+  ChevronDown,
+  ChevronRight,
+  Hourglass,
+  Radio,
+  Trash2,
+  type LucideIcon,
+} from "lucide-react";
+import { useTranslation } from "react-i18next";
+import { subjectLabel, type AttentionItem, type SagiStatus, type SagiSubject } from "./brain";
+import { PET_NAME_MAX } from "./prefs";
+
+/** How many sessions the "Needs you" list shows before pointing at Sessions. */
+const ATTENTION_SHOWN = 4;
+
+/** The pet's name; a click renames it in place (empty = its own name). */
+export function PetNameButton({
+  name,
+  ownName,
+  nickname,
+  onRename,
+}: {
+  name: string;
+  ownName: string;
+  nickname: string;
+  onRename: (name: string) => void;
+}) {
+  const { t } = useTranslation("settings");
+  // The name being typed, or null while not renaming.
+  const [renaming, setRenaming] = useState<string | null>(null);
+  const save = () => {
+    if (renaming === null) return;
+    onRename(renaming);
+    setRenaming(null);
+  };
+  return renaming === null ? (
+    <button
+      type="button"
+      className="max-w-full truncate rounded px-0.5 text-sm font-semibold text-fg-primary hover:bg-surface-4"
+      onClick={() => setRenaming(nickname)}
+      aria-label={t("sagi.panel.rename", { name })}
+      title={t("sagi.panel.rename", { name })}
+    >
+      {name}
+    </button>
+  ) : (
+    <input
+      autoFocus
+      className="w-28 rounded border border-accent bg-surface-1 px-1 py-0.5 text-sm text-fg-primary focus:outline-none"
+      value={renaming}
+      maxLength={PET_NAME_MAX}
+      placeholder={ownName}
+      aria-label={t("sagi.panel.renameLabel")}
+      title={t("sagi.panel.renameHint")}
+      onChange={(e) => setRenaming(e.target.value)}
+      onBlur={save}
+      onKeyDown={(e) => {
+        if (e.key === "Enter") {
+          e.preventDefault();
+          save();
+        } else if (e.key === "Escape") {
+          // Esc cancels the rename only, not the whole chat.
+          e.stopPropagation();
+          e.nativeEvent.stopImmediatePropagation();
+          setRenaming(null);
+        }
+      }}
+    />
+  );
+}
+
+interface SagiInfoProps {
+  attention: ReadonlyArray<AttentionItem>;
+  onOpenSession: (s: SagiSubject) => void;
+  status: SagiStatus;
+  muted: boolean;
+  onToggleMute: () => void;
+  onClearAlerts: () => void;
+  onNavigate: (route: string) => void;
+  /** Expanded at first: the sessions that need the user and the actions. */
+  defaultOpen?: boolean;
+}
+
+/** The status strip under the chat's header. */
+export function SagiInfo({
+  attention,
+  onOpenSession,
+  status,
+  muted,
+  onToggleMute,
+  onClearAlerts,
+  onNavigate,
+  defaultOpen = false,
+}: SagiInfoProps) {
+  const { t } = useTranslation("settings");
+  const [open, setOpen] = useState(defaultOpen);
+  const Chevron = open ? ChevronDown : ChevronRight;
+  return (
+    <div className="pet-chat-info border-b border-border/60 px-3 py-2">
+      <button
+        type="button"
+        className="flex w-full items-center gap-1.5 rounded-lg text-left"
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+        aria-label={t("sagi.chat.status")}
+        title={t("sagi.chat.status")}
+      >
+        <StatChip
+          icon={Radio}
+          label={t("sagi.panel.statLive")}
+          value={status.liveCount}
+          tone={status.liveCount > 0 ? "accent" : "muted"}
+        />
+        <StatChip
+          icon={Hourglass}
+          label={t("sagi.panel.statWaiting")}
+          value={status.waitingCount}
+          tone={status.waitingCount > 0 ? "amber" : "muted"}
+        />
+        <StatChip
+          icon={AlertTriangle}
+          label={t("sagi.panel.statErrored")}
+          value={status.errorCount}
+          tone={status.errorCount > 0 ? "red" : "muted"}
+        />
+        <span
+          className={`ml-auto inline-flex items-center gap-1 rounded-full px-1.5 py-0.5 text-[10px] font-medium ${
+            status.connected
+              ? "bg-status-success/15 text-status-success"
+              : "bg-status-danger/15 text-status-danger"
+          }`}
+        >
+          <span
+            className={`inline-block h-1.5 w-1.5 rounded-full ${
+              status.connected ? "bg-status-success" : "bg-status-danger"
+            }`}
+            aria-hidden
+          />
+          {status.connected ? t("sagi.panel.live") : t("sagi.panel.offline")}
+        </span>
+        <Chevron size={13} className="shrink-0 text-fg-muted" aria-hidden />
+      </button>
+
+      {open && (
+        <div className="mt-2 max-h-48 overflow-y-auto">
+          {/* the sessions that need the user, by name */}
+          {attention.length > 0 && (
+            <div className="mb-2">
+              <div className="mb-1 text-[10px] font-medium uppercase tracking-wider text-fg-muted">
+                {t("sagi.panel.attention")}
+              </div>
+              <ul className="space-y-1">
+                {attention.slice(0, ATTENTION_SHOWN).map((item) => (
+                  <li key={item.id}>
+                    <button
+                      className="group flex w-full items-center gap-2 rounded-lg bg-surface-1 px-2 py-1.5 text-left text-xs transition-colors hover:bg-surface-4"
+                      onClick={() => onOpenSession(item)}
+                      title={item.cwd ?? item.id}
+                    >
+                      {item.kind === "error" ? (
+                        <AlertTriangle
+                          size={13}
+                          className="shrink-0 text-status-danger"
+                          aria-hidden
+                        />
+                      ) : (
+                        <Hourglass size={13} className="shrink-0 text-status-warning" aria-hidden />
+                      )}
+                      <span className="min-w-0 flex-1 truncate text-fg-secondary group-hover:text-fg-primary">
+                        {subjectLabel(item)}
+                      </span>
+                      <span className="shrink-0 text-[10px] text-fg-muted">
+                        {item.kind === "error"
+                          ? t("sagi.panel.attentionError")
+                          : t("sagi.panel.attentionWaiting")}
+                      </span>
+                      <ChevronRight size={12} className="shrink-0 text-fg-muted" aria-hidden />
+                    </button>
+                  </li>
+                ))}
+              </ul>
+              {attention.length > ATTENTION_SHOWN && (
+                <button
+                  className="mt-1 text-[11px] text-accent hover:underline"
+                  onClick={() => onNavigate("/sessions")}
+                >
+                  {t("sagi.panel.attentionMore", { count: attention.length - ATTENTION_SHOWN })}
+                </button>
+              )}
+            </div>
+          )}
+
+          <div className="grid grid-cols-2 gap-1.5">
+            <ActionButton
+              icon={muted ? BellOff : Bell}
+              label={muted ? t("sagi.panel.unmute") : t("sagi.panel.mute")}
+              onClick={onToggleMute}
+            />
+            <ActionButton
+              icon={Trash2}
+              label={t("sagi.panel.clearAlerts")}
+              disabled={status.errorCount === 0}
+              onClick={onClearAlerts}
+            />
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface Tone {
+  wrap: string;
+  value: string;
+  icon: string;
+}
+
+const TONE_MUTED: Tone = {
+  wrap: "border-border bg-surface-1",
+  value: "text-fg-secondary",
+  icon: "text-fg-muted",
+};
+
+const TONES: Record<string, Tone> = {
+  accent: { wrap: "border-accent/30 bg-accent/10", value: "text-fg-primary", icon: "text-accent" },
+  amber: {
+    wrap: "border-status-warning/30 bg-status-warning/10",
+    value: "text-status-warning",
+    icon: "text-status-warning",
+  },
+  red: {
+    wrap: "border-status-danger/30 bg-status-danger/10",
+    value: "text-status-danger",
+    icon: "text-status-danger",
+  },
+  muted: TONE_MUTED,
+};
+
+/** One count, compact: icon, number, label on one line. */
+function StatChip({
+  icon: Icon,
+  label,
+  value,
+  tone,
+}: {
+  icon: LucideIcon;
+  label: string;
+  value: number;
+  tone: string;
+}) {
+  const t = TONES[tone] ?? TONE_MUTED;
+  return (
+    <span className={`inline-flex items-center gap-1 rounded-full border px-1.5 py-0.5 ${t.wrap}`}>
+      <Icon size={11} className={t.icon} aria-hidden />
+      <span className={`text-xs font-semibold tabular-nums ${t.value}`}>{value}</span>
+      <span className="text-[9px] uppercase tracking-wider text-fg-muted">{label}</span>
+    </span>
+  );
+}
+
+function ActionButton({
+  icon: Icon,
+  label,
+  onClick,
+  disabled,
+}: {
+  icon: LucideIcon;
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+}) {
+  return (
+    <button
+      className="flex w-full items-center gap-1.5 rounded-lg bg-surface-1 px-2 py-1.5 text-xs text-fg-secondary transition-colors hover:bg-surface-4 hover:text-fg-primary disabled:cursor-not-allowed disabled:opacity-40"
+      onClick={onClick}
+      disabled={disabled}
+    >
+      <Icon size={14} className="shrink-0" />
+      <span className="truncate">{label}</span>
+    </button>
+  );
+}
@@ -0,0 +1,29 @@
+/**
+ * @file SagiMount.tsx
+ * @description Gate for the Sagi mascot: follows the enabled preference
+ *   (`useSagiEnabled`) and only while it is on lazy-loads and mounts `Sagi` — so
+ *   a disabled mascot costs no chunk download, no brain, no 1 Hz tick and no
+ *   WebSocket reducer.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { lazy, Suspense, useEffect, useState } from "react";
+import { sagiPrefs } from "./prefs";
+
+const Sagi = lazy(() => import("./Sagi").then((m) => ({ default: m.Sagi })));
+
+/** The mascot's enabled preference, followed live (Settings, other tabs). */
+export function useSagiEnabled(): boolean {
+  const [enabled, setEnabled] = useState(() => sagiPrefs.getEnabled());
+  useEffect(() => sagiPrefs.subscribe(() => setEnabled(sagiPrefs.getEnabled())), []);
+  return enabled;
+}
+
+export function SagiMount() {
+  if (!useSagiEnabled()) return null;
+  return (
+    <Suspense fallback={null}>
+      <Sagi />
+    </Suspense>
+  );
+}
@@ -1,285 +0,0 @@
-/**
- * @file SagiPanel.tsx
- * @description Expanded Sagi panel: a live status strip (live / waiting /
- *   errored stat chips + connection state), quick navigation actions, and a
- *   local "Ask" box. Pure presentational - all data and the ask/navigation
- *   behavior are injected by the container.
- * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
- */
-/* =============================================================================
- * MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
- * =============================================================================
- * **Purpose:** Sagi is the optional on-screen mascot assistant — quips, intents, and lightweight event reactions layered above the dashboard chrome.
- *
- * ## Design constraints
- * - Local-first: no telemetry leaves the machine unless the user configures webhooks.
- * - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
- *   philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
- * - Destructive flows stay behind explicit confirmation modals and server-side gates.
- * - Internationalization: user-visible strings belong in i18n JSON, not literals here.
- *
- * ## Remote data & SSH
- * Remote Data Sources let operators aggregate multiple machines. SSH entries describe
- * how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
- * scoped GET via `?sources=`. Health checks and import history surface in Settings.
- *
- * ## Internal dependencies
- * - `./brain`
- *
- * ## Public surface
- * - `SagiPanel` — exported API; see TSDoc on the symbol for behavior.
- *
- * ## Testing pointers
- * - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
- * - Server contract changes require `npm run test:server` and OpenAPI sync.
- *
- * ## Related docs
- * - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
- * - `docs/API.md` — REST reference.
- * - `skills/file-headers/` — mandatory `@author` header policy.
- * ============================================================================= */
-/* -----------------------------------------------------------------------------
- * EXPORT CATALOG — quick index of symbols defined below (documentation only).
- * -----------------------------------------------------------------------------
- * **SagiPanel**
- *   Part of this module's public contract. Downstream imports should treat
- *   the signature and return type as stable unless release notes say otherwise.
- *   When behavior changes, update the `@file` overview and relevant tests.
- *
- * ----------------------------------------------------------------------------- */
-
-import { useState, type FormEvent, type ReactNode } from "react";
-import {
-  Play,
-  Activity,
-  LayoutList,
-  Bell,
-  BellOff,
-  Trash2,
-  X,
-  Send,
-  AlertTriangle,
-  Hourglass,
-  Radio,
-  type LucideIcon,
-} from "lucide-react";
-import type { SagiStatus } from "./brain";
-
-interface SagiPanelProps {
-  status: SagiStatus;
-  muted: boolean;
-  onToggleMute: () => void;
-  onClearAlerts: () => void;
-  onNavigate: (route: string) => void;
-  /** Returns an answer to display, or null when the query was handed off. */
-  onAsk: (query: string) => string | null;
-  onClose: () => void;
-}
-
-export function SagiPanel({
-  status,
-  muted,
-  onToggleMute,
-  onClearAlerts,
-  onNavigate,
-  onAsk,
-  onClose,
-}: SagiPanelProps) {
-  const [query, setQuery] = useState("");
-  const [answer, setAnswer] = useState<string | null>(null);
-
-  const submit = (e: FormEvent) => {
-    e.preventDefault();
-    const result = onAsk(query);
-    setAnswer(result); // null means it handed off (container navigates/closes)
-    setQuery("");
-  };
-
-  return (
-    <div
-      className="w-72 overflow-hidden rounded-2xl border border-border-light bg-surface-2/95 shadow-2xl shadow-black/50 backdrop-blur-md animate-slide-up"
-      role="dialog"
-      aria-label="Sagi companion"
-    >
-      {/* header */}
-      <div className="flex items-center justify-between gap-2 border-b border-border/70 bg-gradient-to-r from-accent/10 to-transparent px-3.5 py-2.5">
-        <div className="flex items-center gap-2 min-w-0">
-          <span className="text-base leading-none" aria-hidden>
-            🐾
-          </span>
-          <span className="text-sm font-semibold text-fg-primary">Sagi</span>
-          <span
-            className={`ml-0.5 inline-flex items-center gap-1 rounded-full px-1.5 py-0.5 text-[10px] font-medium ${
-              status.connected
-                ? "bg-status-success/15 text-status-success"
-                : "bg-status-danger/15 text-status-danger"
-            }`}
-          >
-            <span
-              className={`inline-block h-1.5 w-1.5 rounded-full ${
-                status.connected ? "bg-status-success" : "bg-status-danger"
-              }`}
-              aria-hidden
-            />
-            {status.connected ? "Live" : "Offline"}
-          </span>
-        </div>
-        <button
-          className="rounded-md p-1 text-fg-muted transition-colors hover:bg-surface-4 hover:text-fg-secondary"
-          onClick={onClose}
-          aria-label="Close Sagi"
-        >
-          <X size={15} />
-        </button>
-      </div>
-
-      <div className="p-3">
-        {/* status stat chips */}
-        <div className="mb-3 grid grid-cols-3 gap-1.5">
-          <StatChip
-            icon={Radio}
-            label="live"
-            value={status.liveCount}
-            tone={status.liveCount > 0 ? "accent" : "muted"}
-          />
-          <StatChip
-            icon={Hourglass}
-            label="waiting"
-            value={status.waitingCount}
-            tone={status.waitingCount > 0 ? "amber" : "muted"}
-          />
-          <StatChip
-            icon={AlertTriangle}
-            label="errored"
-            value={status.errorCount}
-            tone={status.errorCount > 0 ? "red" : "muted"}
-          />
-        </div>
-
-        {/* quick actions */}
-        <div className="mb-3 grid grid-cols-2 gap-1.5">
-          <ActionButton icon={Play} label="Run Claude" onClick={() => onNavigate("/workspace")} />
-          <ActionButton icon={Activity} label="Activity" onClick={() => onNavigate("/activity")} />
-          <ActionButton
-            icon={LayoutList}
-            label="Sessions"
-            onClick={() => onNavigate("/sessions")}
-          />
-          <ActionButton
-            icon={AlertTriangle}
-            label="Errored"
-            disabled={status.errorCount === 0}
-            onClick={() => onNavigate("/sessions")}
-          />
-          <ActionButton
-            icon={muted ? BellOff : Bell}
-            label={muted ? "Unmute" : "Mute"}
-            onClick={onToggleMute}
-          />
-          <ActionButton
-            icon={Trash2}
-            label="Clear alerts"
-            disabled={status.errorCount === 0}
-            onClick={onClearAlerts}
-          />
-        </div>
-
-        {/* ask */}
-        <form onSubmit={submit} className="flex items-center gap-1.5">
-          <input
-            className="flex-1 rounded-lg border border-border bg-surface-1 px-2.5 py-1.5 text-xs text-fg-secondary placeholder-fg-muted transition-colors focus:border-accent focus:outline-none focus:ring-1 focus:ring-accent/30"
-            placeholder="Ask Sagi… (e.g. any errors?)"
-            value={query}
-            onChange={(e) => setQuery(e.target.value)}
-            aria-label="Ask Sagi"
-          />
-          <button
-            type="submit"
-            className="flex items-center justify-center rounded-lg bg-accent px-2.5 py-2 text-white transition-colors hover:bg-accent-hover"
-            aria-label="Send"
-          >
-            <Send size={14} />
-          </button>
-        </form>
-        {answer && (
-          <p className="mt-2 rounded-lg bg-surface-1/70 px-2.5 py-2 text-xs leading-relaxed text-fg-secondary">
-            {answer}
-          </p>
-        )}
-      </div>
-    </div>
-  );
-}
-
-interface Tone {
-  wrap: string;
-  value: string;
-  icon: string;
-}
-
-const TONE_MUTED: Tone = {
-  wrap: "border-border bg-surface-1",
-  value: "text-fg-secondary",
-  icon: "text-fg-muted",
-};
-
-const TONES: Record<string, Tone> = {
-  accent: { wrap: "border-accent/30 bg-accent/10", value: "text-fg-primary", icon: "text-accent" },
-  amber: {
-    wrap: "border-status-warning/30 bg-status-warning/10",
-    value: "text-status-warning",
-    icon: "text-status-warning",
-  },
-  red: {
-    wrap: "border-status-danger/30 bg-status-danger/10",
-    value: "text-status-danger",
-    icon: "text-status-danger",
-  },
-  muted: TONE_MUTED,
-};
-
-function StatChip({
-  icon: Icon,
-  label,
-  value,
-  tone,
-}: {
-  icon: LucideIcon;
-  label: string;
-  value: number;
-  tone: string;
-}): ReactNode {
-  const t = TONES[tone] ?? TONE_MUTED;
-  return (
-    <div className={`flex flex-col items-center gap-0.5 rounded-xl border py-1.5 ${t.wrap}`}>
-      <Icon size={13} className={t.icon} aria-hidden />
-      <span className={`text-base font-semibold leading-none tabular-nums ${t.value}`}>
-        {value}
-      </span>
-      <span className="text-[9px] uppercase tracking-wider text-fg-muted">{label}</span>
-    </div>
-  );
-}
-
-function ActionButton({
-  icon: Icon,
-  label,
-  onClick,
-  disabled,
-}: {
-  icon: LucideIcon;
-  label: string;
-  onClick: () => void;
-  disabled?: boolean;
-}) {
-  return (
-    <button
-      className="flex items-center gap-1.5 rounded-lg bg-surface-1 px-2 py-1.5 text-xs text-fg-secondary transition-colors hover:bg-surface-4 hover:text-fg-primary disabled:cursor-not-allowed disabled:opacity-40"
-      onClick={onClick}
-      disabled={disabled}
-    >
-      <Icon size={14} className="shrink-0" />
-      <span className="truncate">{label}</span>
-    </button>
-  );
-}
@@ -1,14 +1,14 @@
 /**
 * @file SpeechBubble.tsx
 * @description Transient speech bubble rendered above the Sagi mascot.
- * Pure presentation — visibility timing and quip selection live in
- * {@link useSagiBrain}; this component only paints the bubble and handles
- * user dismissal.
+ * Pure presentation — visibility timing, coalescing and quip selection live in
+ * {@link useSagiBrain}; this component paints the line, the session(s) it is
+ * about, an Open button when it is about exactly one, and handles dismissal.
 *
 * ## Accessibility
 * Uses `role="status"` with `aria-live="polite"` so screen readers announce
- * new quips without interrupting current speech. Click anywhere on the bubble
- * to dismiss early.
+ * new quips without interrupting current speech. Click the bubble to dismiss
+ * it early; its Open button opens the session instead.
 *
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
@@ -51,28 +51,53 @@
 *
 * ----------------------------------------------------------------------------- */

+import { useTranslation } from "react-i18next";
+import type { SagiBubble } from "./useSagiBrain";
+import type { SagiSubject } from "./brain";
+
 /** Props for {@link SpeechBubble}. */
 interface SpeechBubbleProps {
-  /** Quip text to display inside the bubble. */
-  text: string;
+  bubble: SagiBubble;
  /** Called when the user clicks to dismiss. */
  onDismiss: () => void;
+  /** Opens the session the bubble is about. */
+  onOpen?: (subject: SagiSubject) => void;
 }

 /**
 * Animated speech bubble above Sagi.
 * @param props See {@link SpeechBubbleProps}.
 */
-export function SpeechBubble({ text, onDismiss }: SpeechBubbleProps) {
+export function SpeechBubble({ bubble, onDismiss, onOpen }: SpeechBubbleProps) {
+  const { t } = useTranslation("settings");
+  const { text, detail, subject, tone } = bubble;
  return (
    <div
      className="sagi-bubble sagi-bubble-enter"
+      data-tone={tone}
      role="status"
      aria-live="polite"
      onClick={onDismiss}
-      title="Dismiss"
+      title={t("sagi.bubbleDismiss")}
    >
-      {text}
+      <div>{text}</div>
+      {(detail || (subject && onOpen)) && (
+        <div className="sagi-bubble-detail">
+          {detail && <span className="sagi-bubble-subject">{detail}</span>}
+          {subject && onOpen && (
+            <button
+              type="button"
+              className="sagi-bubble-open"
+              onClick={(e) => {
+                e.stopPropagation();
+                onOpen(subject);
+              }}
+            >
+              {t("sagi.bubbleOpen")}
+            </button>
+          )}
+        </div>
+      )}
    </div>
  );
 }
@@ -0,0 +1,46 @@
+/**
+ * @file PetChat.test.ts
+ * @description Unit tests for the pet chat's transcript-to-bubbles folding (`chatLines`).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { describe, it, expect } from "vitest";
+import { chatLines } from "../PetChat";
+import type { TranscriptMessage } from "../../../lib/types";
+
+const msg = (m: Partial<TranscriptMessage>): TranscriptMessage =>
+  ({ type: "user", timestamp: null, content: [], ...m }) as TranscriptMessage;
+
+describe("chatLines", () => {
+  it("keeps the user's words and the assistant's prose, folding tool calls into one chip", () => {
+    const lines = chatLines([
+      msg({ type: "user", sender: "user", content: [{ type: "text", text: "hi" }] }),
+      msg({
+        type: "assistant",
+        content: [
+          { type: "thinking", text: "hmm" },
+          { type: "tool_use", name: "Read" },
+        ],
+      }),
+      msg({ type: "user", sender: "tool", content: [{ type: "tool_result", output: "x" }] }),
+      msg({
+        type: "assistant",
+        content: [
+          { type: "tool_use", name: "Read" },
+          { type: "text", text: "hello!" },
+        ],
+      }),
+    ]);
+    expect(lines.map((l) => (l.role === "tools" ? l.names : l.text))).toEqual([
+      "hi",
+      ["Read", "Read"],
+      "hello!",
+    ]);
+  });
+
+  it("drops Claude Code's own injected lines", () => {
+    const lines = chatLines([
+      msg({ sender: "user", content: [{ type: "text", text: "<command-name>/clear</command-name>" }] }),
+    ]);
+    expect(lines).toEqual([]);
+  });
+});
@@ -0,0 +1,358 @@
+/**
+ * @file Pets.test.tsx
+ * @description The mascot's custom pets: `PetSprite` plays the spritesheet
+ * row of Sagi's mood and steps through its frames (a still image bobs instead),
+ * and `PetMenu` hides the mascot, sizes it, picks Sagi / a featured pet
+ * (downloading it on the first pick) / an own pet, deletes an own pet (falling
+ * back to Sagi when it was the one worn), and uploads an image; Settings →
+ * Pet (`PetSettings`) does the same from a grid, plus show / bubbles / size.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, act, waitFor } from "@testing-library/react";
+
+vi.mock("../../../lib/api", async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  const own = {
+    id: "p-aaaaaaaaaaaa",
+    displayName: "My cat",
+    description: "",
+    kind: "image",
+    source: "upload",
+  };
+  return {
+    ...actual,
+    api: {
+      pets: {
+        spriteUrl: (id: string) => `/api/pets/${id}/sprite`,
+        list: vi.fn(async () => ({
+          pets: [own],
+          featured: [
+            { id: "goku", displayName: "Goku", by: "hackminit", installed: false, page: "" },
+          ],
+          sheet: { width: 1536, height: 1872, cellWidth: 192, cellHeight: 208 },
+        })),
+        installFeatured: vi.fn(async () => ({
+          pet: {
+            id: "cp-goku",
+            displayName: "Goku",
+            description: "",
+            kind: "codex",
+            source: "featured",
+            featuredId: "goku",
+          },
+        })),
+        upload: vi.fn(async () => ({
+          pet: {
+            id: "p-bbbbbbbbbbbb",
+            displayName: "Dog",
+            description: "",
+            kind: "image",
+            source: "upload",
+          },
+        })),
+        importBundle: vi.fn(),
+        remove: vi.fn(async () => ({ ok: true })),
+      },
+    },
+  };
+});
+
+import { api } from "../../../lib/api";
+import { PetSprite } from "../PetSprite";
+import { PetMenu } from "../PetMenu";
+import { PetSettings } from "../../settings/PetSettings";
+import { sagiPrefs } from "../prefs";
+import { settleConfirm, subscribeConfirm, type PendingConfirm } from "../../../lib/confirm";
+import { subscribeToasts, type ToastItem } from "../../../lib/toast";
+
+/** Answer the pending confirmDialog (asserting one is open). */
+function answerConfirm(ok: boolean) {
+  let pending: PendingConfirm | null = null;
+  subscribeConfirm((p) => (pending = p))();
+  expect(pending).not.toBeNull();
+  act(() => settleConfirm(ok));
+}
+
+describe("PetSprite", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("plays the row of the mood and steps through its frames", () => {
+    const { rerender } = render(
+      <PetSprite
+        id="cp-goku"
+        kind="codex"
+        mood="thinking"
+        size={104}
+        reducedMotion={false}
+        onBroken={() => {}}
+      />
+    );
+    const sprite = screen.getByTestId("pet-sprite");
+    // 104 px tall = half a 208 px cell: row 7 (running) starts 7 × 104 px down.
+    expect(sprite.dataset.row).toBe("7");
+    expect(sprite.style.backgroundPosition).toBe("0px -728px");
+    act(() => vi.advanceTimersByTime(110));
+    expect(sprite.style.backgroundPosition).toBe("0px -728px"); // Codex: 120 ms a frame
+    act(() => vi.advanceTimersByTime(10));
+    expect(sprite.style.backgroundPosition).toBe("-96px -728px");
+    rerender(
+      <PetSprite
+        id="cp-goku"
+        kind="codex"
+        mood="worried"
+        size={104}
+        reducedMotion={false}
+        onBroken={() => {}}
+      />
+    );
+    expect(screen.getByTestId("pet-sprite").dataset.row).toBe("5");
+  });
+
+  it("runs the way it is dragged and waves on hover, over its mood", () => {
+    const props = {
+      id: "cp-goku",
+      kind: "codex" as const,
+      mood: "thinking" as const,
+      size: 208,
+      reducedMotion: false,
+      onBroken: () => {},
+    };
+    const { rerender } = render(<PetSprite {...props} action="run-left" />);
+    expect(screen.getByTestId("pet-sprite").dataset.row).toBe("2");
+    rerender(<PetSprite {...props} action="run-right" />);
+    expect(screen.getByTestId("pet-sprite").dataset.row).toBe("1");
+    rerender(<PetSprite {...props} action="wave" />);
+    expect(screen.getByTestId("pet-sprite").dataset.row).toBe("3");
+    rerender(<PetSprite {...props} action={null} />);
+    expect(screen.getByTestId("pet-sprite").dataset.row).toBe("7");
+  });
+
+  it("plays idle at the drawn pace, the last frame barely longer than the rest", () => {
+    render(
+      <PetSprite
+        id="cp-goku"
+        kind="codex"
+        mood="idle"
+        size={208}
+        reducedMotion={false}
+        onBroken={() => {}}
+      />
+    );
+    const sprite = screen.getByTestId("pet-sprite");
+    act(() => vi.advanceTimersByTime(280 + 110 + 110 + 140 + 140)); // → the 6th, last frame
+    expect(sprite.style.backgroundPosition).toBe("-960px 0px");
+    act(() => vi.advanceTimersByTime(310));
+    expect(sprite.style.backgroundPosition).toBe("-960px 0px");
+    act(() => vi.advanceTimersByTime(10)); // 320 ms, not a long hold
+    expect(sprite.style.backgroundPosition).toBe("0px 0px");
+  });
+
+  it("plays a moment three times, then settles into idle; a condition keeps looping", () => {
+    const props = { id: "cp-goku", kind: "codex" as const, size: 208, reducedMotion: false };
+    const { rerender } = render(<PetSprite {...props} mood="happy" onBroken={() => {}} />);
+    const sprite = screen.getByTestId("pet-sprite");
+    expect(sprite.dataset.row).toBe("4"); // jumping: 5 frames, 4 × 140 + 280 ms
+    act(() => vi.advanceTimersByTime(3 * 840 - 1));
+    expect(sprite.dataset.row).toBe("4");
+    act(() => vi.advanceTimersByTime(1));
+    expect(sprite.dataset.row).toBe("0");
+    rerender(<PetSprite {...props} mood="thinking" onBroken={() => {}} />);
+    act(() => vi.advanceTimersByTime(10_000));
+    expect(sprite.dataset.row).toBe("7");
+  });
+
+  it("looks toward the pointer on a v2 sheet, only while idle", () => {
+    // A v2 atlas is 11 rows tall; the sprite learns that from the loaded image.
+    vi.stubGlobal(
+      "Image",
+      class {
+        naturalHeight = 2288;
+        onload: (() => void) | null = null;
+        onerror: (() => void) | null = null;
+        set src(_: string) {
+          this.onload?.();
+        }
+      }
+    );
+    const props = { id: "cp-goku", kind: "codex" as const, size: 208, reducedMotion: false };
+    const { rerender } = render(<PetSprite {...props} mood="idle" gaze={12} onBroken={() => {}} />);
+    const sprite = screen.getByTestId("pet-sprite");
+    // Pose 12 (270°, left) = row 10, column 4.
+    expect(sprite.style.backgroundPosition).toBe("-768px -2080px");
+    expect(sprite.style.backgroundSize).toBe("1536px 2288px");
+    rerender(<PetSprite {...props} mood="thinking" gaze={12} onBroken={() => {}} />);
+    expect(sprite.dataset.row).toBe("7");
+    vi.unstubAllGlobals();
+  });
+
+  it("ignores the pointer on a v1 sheet, which has no gaze rows", () => {
+    render(
+      <PetSprite
+        id="cp-goku"
+        kind="codex"
+        mood="idle"
+        gaze={4}
+        size={208}
+        reducedMotion={false}
+        onBroken={() => {}}
+      />
+    );
+    expect(screen.getByTestId("pet-sprite").style.backgroundPosition).toBe("0px 0px");
+  });
+
+  it("holds the first frame under reduced motion", () => {
+    render(
+      <PetSprite
+        id="cp-goku"
+        kind="codex"
+        mood="idle"
+        size={208}
+        reducedMotion
+        onBroken={() => {}}
+      />
+    );
+    act(() => vi.advanceTimersByTime(1000));
+    expect(screen.getByTestId("pet-sprite").style.backgroundPosition).toBe("0px 0px");
+  });
+
+  it("shows an uploaded image still, and reports one that will not load", () => {
+    const broken = vi.fn();
+    const { container } = render(
+      <PetSprite
+        id="p-aaaaaaaaaaaa"
+        kind="image"
+        mood="idle"
+        size={80}
+        reducedMotion={false}
+        onBroken={broken}
+      />
+    );
+    const img = container.querySelector("img") as HTMLImageElement;
+    expect(img.getAttribute("src")).toBe("/api/pets/p-aaaaaaaaaaaa/sprite");
+    fireEvent.error(img);
+    expect(broken).toHaveBeenCalled();
+  });
+});
+
+describe("PetMenu", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    vi.clearAllMocks();
+  });
+  const renderMenu = () =>
+    render(<PetMenu pet={sagiPrefs.getPet()} size={68} onClose={() => {}} onSettings={() => {}} />);
+
+  it("hides the mascot and sizes it", () => {
+    renderMenu();
+    fireEvent.change(screen.getByTestId("pet-size"), { target: { value: "250" } });
+    expect(sagiPrefs.getSize()).toBe(250);
+    let toasts: ToastItem[] = [];
+    const off = subscribeToasts((i) => (toasts = i));
+    fireEvent.click(screen.getByText("Hide pet"));
+    expect(sagiPrefs.getEnabled()).toBe(false);
+    // Says where to bring it back.
+    expect(toasts.some((x) => /Settings → Appearance/.test(x.message))).toBe(true);
+    off();
+  });
+
+  it("downloads a featured pet on its first pick, then wears it", async () => {
+    renderMenu();
+    fireEvent.click(screen.getByTestId("pet-choose"));
+    fireEvent.click(await screen.findByTestId("pet-featured-goku"));
+    await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "cp-goku", kind: "codex", name: "Goku" }));
+    expect(api.pets.installFeatured).toHaveBeenCalledWith("goku");
+  });
+
+  it("deleting the pet being worn puts Sagi back", async () => {
+    sagiPrefs.setPet({ id: "p-aaaaaaaaaaaa", kind: "image" });
+    renderMenu();
+    fireEvent.click(screen.getByTestId("pet-choose"));
+    fireEvent.click(await screen.findByTestId("pet-delete-p-aaaaaaaaaaaa"));
+    // Asks first: nothing is deleted on one click.
+    expect(api.pets.remove).not.toHaveBeenCalled();
+    answerConfirm(true);
+    await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "sagi" }));
+    expect(api.pets.remove).toHaveBeenCalledWith("p-aaaaaaaaaaaa");
+  });
+
+  it("uploads an image and wears it", async () => {
+    renderMenu();
+    const file = new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], "Dog.png", {
+      type: "image/png",
+    });
+    fireEvent.change(screen.getByTestId("pet-image-input"), { target: { files: [file] } });
+    await waitFor(() =>
+      expect(sagiPrefs.getPet()).toEqual({ id: "p-bbbbbbbbbbbb", kind: "image", name: "Dog" })
+    );
+    expect(api.pets.upload).toHaveBeenCalledWith(file);
+  });
+});
+
+describe("PetSettings", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    vi.clearAllMocks();
+  });
+
+  it("shows, mutes and sizes the mascot, following the prefs live", async () => {
+    render(<PetSettings />);
+    fireEvent.change(screen.getByTestId("pet-settings-size"), { target: { value: "120" } });
+    expect(sagiPrefs.getSize()).toBe(120);
+    expect(screen.getByText("120px")).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("switch", { name: /Speech bubbles/ }));
+    expect(sagiPrefs.getMuted()).toBe(true);
+    fireEvent.click(screen.getByRole("switch", { name: /Show Sagi/ }));
+    expect(sagiPrefs.getEnabled()).toBe(false);
+    // A change made elsewhere (the right-click menu) shows here at once.
+    act(() => sagiPrefs.setSize(200));
+    expect(screen.getByText("200px")).toBeInTheDocument();
+  });
+
+  it("downloads a featured pet on its first pick, wears an own one, deletes it back to Sagi", async () => {
+    render(<PetSettings />);
+    fireEvent.click(await screen.findByTestId("pet-card-featured-goku"));
+    await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "cp-goku", kind: "codex", name: "Goku" }));
+    expect(api.pets.installFeatured).toHaveBeenCalledWith("goku");
+
+    fireEvent.click(screen.getByTestId("pet-card-own-p-aaaaaaaaaaaa"));
+    expect(sagiPrefs.getPet()).toEqual({ id: "p-aaaaaaaaaaaa", kind: "image", name: "My cat" });
+    fireEvent.click(screen.getByTestId("pet-card-own-p-aaaaaaaaaaaa-delete"));
+    answerConfirm(true);
+    await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "sagi" }));
+    expect(api.pets.remove).toHaveBeenCalledWith("p-aaaaaaaaaaaa");
+  });
+
+  it("uploads an image and wears it", async () => {
+    render(<PetSettings />);
+    const file = new File([new Uint8Array([0x89, 0x50])], "Dog.png", { type: "image/png" });
+    fireEvent.change(screen.getByTestId("pet-settings-image-input"), { target: { files: [file] } });
+    await waitFor(() =>
+      expect(sagiPrefs.getPet()).toEqual({ id: "p-bbbbbbbbbbbb", kind: "image", name: "Dog" })
+    );
+  });
+
+  it("a cancelled delete keeps the pet", async () => {
+    render(<PetSettings />);
+    fireEvent.click(await screen.findByTestId("pet-card-own-p-aaaaaaaaaaaa-delete"));
+    answerConfirm(false);
+    await act(async () => {});
+    expect(api.pets.remove).not.toHaveBeenCalled();
+  });
+
+  it("disables size and bubbles while hidden, and resets to defaults", async () => {
+    sagiPrefs.setEnabled(false);
+    sagiPrefs.setSize(200);
+    sagiPrefs.setMuted(true);
+    render(<PetSettings />);
+    expect(screen.getByTestId("pet-settings-size")).toBeDisabled();
+    expect(screen.getByRole("switch", { name: /Speech bubbles/ })).toBeDisabled();
+    fireEvent.click(screen.getByRole("button", { name: /Reset to defaults/ }));
+    answerConfirm(true);
+    await waitFor(() => expect(sagiPrefs.getEnabled()).toBe(true));
+    expect(sagiPrefs.getSize()).toBe(68);
+    expect(sagiPrefs.getMuted()).toBe(false);
+    expect(sagiPrefs.getPet()).toEqual({ id: "sagi" });
+  });
+});
@@ -1,14 +1,24 @@
 /**
 * @file Sagi.test.tsx
- * @description Render tests for the Sagi companion component — mounting, mood rendering, the ⌘B panel toggle, and accessibility attributes.
+ * @description Render tests for the Sagi companion component — mounting, mood rendering, the ⌘B chat toggle (the chat window is the pet's whole UI: status strip, local answers, New chat stopping the old session), and accessibility attributes.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { render, screen, fireEvent, act, cleanup, within } from "@testing-library/react";
+import {
+  render,
+  renderHook,
+  screen,
+  fireEvent,
+  act,
+  cleanup,
+  within,
+} from "@testing-library/react";
+import { useSagiPosition } from "../useSagiPosition";
 import { MemoryRouter } from "react-router-dom";
 import { Sagi } from "../Sagi";
 import { eventBus } from "../../../lib/eventBus";
+import { api } from "../../../lib/api";
 import type { WSMessage, Session } from "../../../lib/types";

 function renderSagi() {
@@ -45,13 +55,13 @@ describe("Sagi widget", () => {
    expect(screen.getByRole("img", { name: /sagi/i })).toBeInTheDocument();
  });

-  it("opens the panel on click and answers a local status question", () => {
+  it("opens the chat on click and answers a local status question there", () => {
    renderSagi();
    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
-    const panel = screen.getByRole("dialog", { name: /sagi companion/i });
+    const panel = screen.getByRole("dialog", { name: /chat with sagi/i });
    expect(panel).toBeInTheDocument();

-    const input = within(panel).getByLabelText(/ask sagi/i);
+    const input = within(panel).getByLabelText(/ask sagi anything/i);
    fireEvent.change(input, { target: { value: "status" } });
    fireEvent.submit(input.closest("form")!);
    expect(within(panel).getByText(/live ·/i)).toBeInTheDocument();
@@ -79,16 +89,114 @@ describe("Sagi widget", () => {
    expect(within(btn).getByText("1")).toBeInTheDocument();
  });

-  it("reflects the live count in the panel status", () => {
+  it("names the errored session in its bubble and in the chat", () => {
+    renderSagi();
+    act(() => {
+      eventBus.publish({
+        type: "session_updated",
+        data: { id: "a", status: "error", name: "Fix login", cwd: "/w/app", lane_id: 3 } as Session,
+        timestamp: "t",
+      });
+    });
+    const bubble = screen.getByRole("status");
+    expect(within(bubble).getByText("Fix login")).toBeInTheDocument();
+    expect(within(bubble).getByRole("button", { name: "Open" })).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    const panel = screen.getByRole("dialog", { name: /chat with sagi/i });
+    expect(within(panel).getByText("Needs you")).toBeInTheDocument();
+    expect(within(panel).getByRole("button", { name: /Fix login/ })).toBeInTheDocument();
+  });
+
+  it("stays quiet about a cleared error when that session updates again", () => {
+    renderSagi();
+    act(() => {
+      eventBus.publish(sessionMsg("a", "error"));
+    });
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    fireEvent.click(screen.getByRole("button", { name: "Clear alerts" }));
+    act(() => {
+      eventBus.publish(sessionMsg("a", "error"));
+    });
+    const btn = screen.getByRole("button", { name: /close sagi/i, expanded: true });
+    expect(within(btn).queryByText("1")).not.toBeInTheDocument();
+    expect(JSON.parse(localStorage.getItem("agenthub.pet.dismissedErrors")!)).toEqual(["a"]);
+  });
+
+  it("renames the pet from the chat header", () => {
+    renderSagi();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    fireEvent.click(screen.getByRole("button", { name: /rename sagi/i }));
+    const input = screen.getByLabelText("Pet name");
+    fireEvent.change(input, { target: { value: "Mochi" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(screen.getByRole("dialog", { name: /chat with mochi/i })).toBeInTheDocument();
+    expect(screen.getByLabelText(/ask mochi anything/i)).toBeInTheDocument();
+  });
+
+  it("hands a question it cannot answer to the AI", () => {
+    localStorage.setItem("agenthub.defaultTool", "claude");
+    const ensure = vi.spyOn(api.lanes, "ensure").mockReturnValue(new Promise(() => {}));
+    renderSagi();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    const chat = screen.getByRole("dialog", { name: /chat with sagi/i });
+    const input = within(chat).getByLabelText(/ask sagi anything/i);
+    fireEvent.change(input, { target: { value: "write me a haiku" } });
+    fireEvent.submit(input.closest("form")!);
+    expect(within(chat).getByText("write me a haiku")).toBeInTheDocument();
+    expect(ensure).toHaveBeenCalledWith({ title: "Sagi" });
+    ensure.mockRestore();
+  });
+
+  it("reopens the remembered chat, and New chat stops its session", async () => {
+    localStorage.setItem(
+      "agenthub.pet.chat",
+      JSON.stringify({ laneId: 7, runId: "agenthub-lane-7-1", tool: "claude" })
+    );
+    const get = vi
+      .spyOn(api.run, "get")
+      .mockReturnValue(new Promise(() => {}) as ReturnType<typeof api.run.get>);
+    const kill = vi.spyOn(api.run, "kill").mockResolvedValue({ ok: true });
+    renderSagi();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    expect(screen.getByRole("button", { name: /open in workspace/i })).toBeInTheDocument();
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: /new chat/i }));
+    });
+    expect(kill).toHaveBeenCalledWith("agenthub-lane-7-1", { archive: true });
+    expect(localStorage.getItem("agenthub.pet.chat")).toBeNull();
+    expect(screen.queryByRole("button", { name: /open in workspace/i })).not.toBeInTheDocument();
+    get.mockRestore();
+    kill.mockRestore();
+  });
+
+  it("a pat shows its reaction on the pet even while the chat is open", () => {
+    renderSagi();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    fireEvent.click(screen.getByRole("button", { name: /pat sagi/i }));
+    const pet = screen.getByRole("button", { name: /close sagi/i, expanded: true });
+    expect(pet.querySelector(".sagi-reaction-text")?.textContent).toBeTruthy();
+  });
+
+  it("stroking the pet back and forth pats it", () => {
+    renderSagi();
+    const pet = screen.getByRole("button", { name: /open sagi companion/i });
+    const xs = [100, 130, 100, 130, 100, 130, 100];
+    act(() => {
+      for (const x of xs) fireEvent.pointerMove(pet, { clientX: x, clientY: 50, buttons: 0 });
+    });
+    expect(pet.querySelector(".sagi-reaction-text")).not.toBeNull();
+  });
+
+  it("reflects the live count in the chat status", () => {
    renderSagi();
    act(() => {
      eventBus.publish(sessionMsg("a", "active"));
      eventBus.publish(sessionMsg("b", "active"));
    });
    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
-    const panel = screen.getByRole("dialog", { name: /sagi companion/i });
+    const panel = screen.getByRole("dialog", { name: /chat with sagi/i });
    // The "live" stat chip shows value 2 next to its label.
-    const liveChip = within(panel).getByText("live").closest("div")!;
+    const liveChip = within(panel).getByText("live").closest("span.rounded-full")! as HTMLElement;
    expect(within(liveChip).getByText("2")).toBeInTheDocument();
  });

@@ -98,7 +206,7 @@ describe("Sagi widget", () => {
    expect(screen.queryByRole("button", { name: /open sagi companion/i })).not.toBeInTheDocument();
  });

-  it("a tap (no movement) still opens the panel", () => {
+  it("a tap (no movement) still opens the chat", () => {
    renderSagi();
    const btn = screen.getByRole("button", { name: /open sagi companion/i });
    act(() => {
@@ -106,7 +214,7 @@ describe("Sagi widget", () => {
      fireEvent.pointerUp(btn, { clientX: 990, clientY: 700 });
    });
    fireEvent.click(btn);
-    expect(screen.getByRole("dialog", { name: /sagi companion/i })).toBeInTheDocument();
+    expect(screen.getByRole("dialog", { name: /chat with sagi/i })).toBeInTheDocument();
  });

  it("dragging snaps to an edge, persists position, and does not open the panel", () => {
@@ -135,7 +243,7 @@ describe("Sagi widget", () => {
      fireEvent.pointerUp(btn, { clientX: 992, clientY: 701 });
    });
    fireEvent.click(btn);
-    expect(screen.getByRole("dialog", { name: /sagi companion/i })).toBeInTheDocument();
+    expect(screen.getByRole("dialog", { name: /chat with sagi/i })).toBeInTheDocument();
    // No position was persisted because no real drag happened.
    expect(localStorage.getItem("agent-dashboard-sagi-pos")).toBeNull();
  });
@@ -147,4 +255,67 @@ describe("Sagi widget", () => {
    // Left-docked → inline left equals the edge margin (16px).
    expect(btn.style.left).toBe("16px");
  });
+
+  it("Ctrl/Cmd+B is ignored while typing in a field", () => {
+    renderSagi();
+    const ta = document.createElement("textarea");
+    document.body.appendChild(ta);
+    ta.focus();
+    act(() => {
+      fireEvent.keyDown(ta, { key: "b", ctrlKey: true });
+    });
+    expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+    ta.remove();
+  });
+
+  it("Ctrl/Cmd+B is left to the browser while the mascot is hidden", () => {
+    localStorage.setItem("agent-dashboard-sagi-enabled", "false");
+    renderSagi();
+    const ev = new KeyboardEvent("keydown", { key: "b", ctrlKey: true, cancelable: true });
+    window.dispatchEvent(ev);
+    expect(ev.defaultPrevented).toBe(false);
+  });
+
+  it("docks bottom-right above the status bar by default", () => {
+    renderSagi();
+    const btn = screen.getByRole("button", { name: /open sagi companion/i }) as HTMLElement;
+    const top = parseFloat(btn.style.top);
+    const size = parseFloat(btn.style.width);
+    // Bottom edge sits above the 24px status bar plus the edge margin.
+    expect(top + size).toBe(window.innerHeight - 16 - 24);
+  });
+
+  it("arrow keys move the focused avatar and persist it", () => {
+    renderSagi();
+    const btn = screen.getByRole("button", { name: /open sagi companion/i }) as HTMLElement;
+    const before = parseFloat(btn.style.top);
+    act(() => {
+      fireEvent.keyDown(btn, { key: "ArrowUp" });
+    });
+    expect(parseFloat(btn.style.top)).toBeLessThan(before);
+    act(() => {
+      fireEvent.keyDown(btn, { key: "ArrowLeft" });
+    });
+    expect(btn.style.left).toBe("16px");
+    expect(JSON.parse(localStorage.getItem("agent-dashboard-sagi-pos") || "{}").side).toBe("left");
+  });
+});
+
+describe("useSagiPosition moving", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("names the drag's direction and settles once the pointer rests", () => {
+    const { result } = renderHook(() => useSagiPosition(68));
+    const target = { setPointerCapture() {}, releasePointerCapture() {} };
+    const ev = (x: number) =>
+      ({ button: 0, pointerId: 1, clientX: x, clientY: 300, currentTarget: target }) as never;
+    act(() => result.current.onPointerDown(ev(500)));
+    act(() => result.current.onPointerMove(ev(480)));
+    expect(result.current.moving).toBe("left");
+    act(() => result.current.onPointerMove(ev(520)));
+    expect(result.current.moving).toBe("right");
+    act(() => vi.advanceTimersByTime(400));
+    expect(result.current.moving).toBeNull();
+  });
 });
@@ -225,6 +225,43 @@ describe("clearErrors", () => {
    expect(statusOf(s).liveCount).toBe(1);
    expect(s.worriedUntil).toBe(0);
  });
+
+  it("keeps a cleared session quiet while it stays errored", () => {
+    let s = initialSagiState(T0);
+    ({ state: s } = reduceSagi(s, sessionMsg("b", "error"), T0));
+    s = clearErrors(s);
+    const again = reduceSagi(s, sessionMsg("b", "error", T0 + 1), T0 + 1);
+    expect(again.pulse).toBeNull();
+    expect(statusOf(again.state).errorCount).toBe(0);
+    expect(again.state.worriedUntil).toBe(0);
+    const ev = reduceSagi(
+      again.state,
+      { type: "new_event", data: { session_id: "b", event_type: "toolError" }, timestamp: "" } as WSMessage,
+      T0 + 2
+    );
+    expect(ev.pulse).toBeNull();
+    expect(seedSessions(s, [{ id: "b", status: "error" }], T0).sessions.b).toBeUndefined();
+  });
+
+  it("alerts again once a cleared session recovers and fails anew", () => {
+    let s = initialSagiState(T0);
+    ({ state: s } = reduceSagi(s, sessionMsg("b", "error"), T0));
+    s = clearErrors(s);
+    ({ state: s } = reduceSagi(s, sessionMsg("b", "active"), T0));
+    expect(s.dismissed).not.toHaveProperty("b");
+    const r = reduceSagi(s, sessionMsg("b", "error"), T0);
+    expect(r.pulse).toBe("error");
+  });
+});
+
+describe("error alerts fire on the transition only", () => {
+  it("does not re-alert on each update of a still-errored session", () => {
+    let s = initialSagiState(T0);
+    ({ state: s } = reduceSagi(s, sessionMsg("a", "error"), T0));
+    const r = reduceSagi(s, sessionMsg("a", "error"), T0 + 10_000);
+    expect(r.pulse).toBeNull();
+    expect(statusOf(r.state).errorCount).toBe(1);
+  });
 });

 // Reference the imported constant so it is exercised and tsc-clean.
--- a/Show More
+++ b/Show More
				`@@ -1 +0,0 @@`
				`{"reason":"idle timeout","timestamp":1774536800234}`
				`@@ -0,0 +1 @@`
				<svg version="1.2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 250" width="250" height="250"><defs><linearGradient id="P" gradientUnits="userSpaceOnUse"/><linearGradient id="g1" x2="1" href="#P" gradientTransform="matrix(0,249.335,-249.128,0,125,.332)"><stop stop-color="#b1a7ff"/><stop offset=".5" stop-color="#7a9dff"/><stop offset="1" stop-color="#3941ff"/></linearGradient></defs><style>.a{fill:url(#g1)}</style><path class="a" d="m84.3 5.1q3.7-1.5 7.7-2.6 3.9-1 7.9-1.6 4-0.5 8.1-0.6 4 0 8 0.5 20.7 2.4 37.1 17.7 0.1 0.1 0.4 0.3 0.1 0 0.2 0 0 0 0.2 0 0 0 0.1 0 0 0 0.1 0 5.2-1.4 10.7-1.9 5.4-0.4 10.7 0.1 5.5 0.4 10.7 1.9 5.2 1.3 10.1 3.6l0.6 0.4 1.6 0.8q5.2 2.5 9.7 6.1 4.7 3.4 8.6 7.7 3.8 4.3 6.9 9.2 3 4.8 5.2 10.2 4.3 10.5 4.3 22.1 0.2 2.1 0 4.2-0.1 2.2-0.2 4.3-0.3 2.1-0.7 4.3-0.4 2.1-0.9 4.1 0 0.2 0 0.4 0 0.2 0 0.5 0 0.1 0.1 0.4 0.1 0.1 0.3 0.3 12.3 12.6 16.3 30 6 29.7-12.2 53.5l-1.9 2.2q-3 3.5-6.5 6.4-3.4 3.1-7.3 5.5-3.8 2.4-8.1 4.2-4.1 1.9-8.5 3.2-0.3 0-0.4 0.2-0.3 0-0.4 0.1-0.1 0.1-0.3 0.4 0 0.1-0.1 0.3c-2.7 7.7-5.3 14.2-10.2 20.7-12.5 16.5-30.8 25.5-51.5 25.5q-24.6-0.1-43.6-18.1-0.2-0.1-0.4-0.2-0.2-0.1-0.4-0.1-0.2 0-0.3 0-0.3 0-0.4 0c-5.4 1.7-10.9 1.9-16.7 1.9q-3.5 0-7-0.5-3.4-0.4-6.9-1.2-3.3-0.8-6.6-2-3.3-1.2-6.4-2.8-3.3-1.6-6.4-3.6-3-2-5.8-4.3-3-2.3-5.5-5-2.5-2.6-4.6-5.6c-2.2-2.7-4.3-5.4-5.8-8.5q-0.8-1.6-1.6-3.2-0.6-1.7-1.3-3.3-0.7-1.7-1.2-3.4-0.5-1.6-1-3.4-1.1-4-1.6-7.9-0.6-4-0.6-8 0-4 0.6-8 0.4-4 1.4-8 0 0 0-0.1 0-0.1 0-0.1 0.2-0.2 0.2-0.3 0-0.1-0.2-0.1 0-0.2 0-0.3 0-0.1-0.1-0.1 0-0.2 0-0.2-0.1-0.1-0.1-0.1-2.4-2.5-4.6-5.2-2.1-2.7-4-5.4-1.7-3-3.2-6-1.5-3.1-2.6-6.3-0.8-2-1.3-4.1-0.7-2-1.1-4-0.4-2.1-0.7-4.2-0.2-2.2-0.4-4.3-0.2-2.8-0.1-5.6 0-2.8 0.3-5.4 0.1-2.8 0.6-5.6 0.4-2.8 1.1-5.5 7-23.1 26.9-36.3 4.3-2.9 8.2-4.5 4.5-1.9 9-3.2 0.2 0 0.3-0.1 0.1-0.2 0.3-0.3 0.1 0 0.1-0.3 0.1-0.1 0.1-0.2 1-3.1 2.2-6 1-2.9 2.5-5.7 1.5-3 3.2-5.6 1.7-2.7 3.7-5.1 2.5-3.2 5.3-5.9 3-2.8 6.1-5.4 3.2-2.4 6.8-4.4 3.5-2 7.2-3.5zm48.3 146.4c-2.3 0.1-4.4 1-6 2.8-1.5 1.6-2.4 3.7-2.4 5.9 0 2.3 0.9 4.4 2.4 6.2 1.6 1.6 3.7 2.5 6 2.6h50.4c2.4 0.1 4.8-0.6 6.5-2.4 1.7-1.6 2.8-4 2.8-6.4 0-2.4-1.1-4.7-2.8-6.3-1.7-1.8-4.1-2.6-6.5-2.4zm-56.7-64.9c-1.2-1.9-3-3.4-5.3-3.9-2.2-0.5-4.5-0.3-6.5 0.9-2 1.1-3.5 3-4.1 5.2-0.7 2.2-0.4 4.6 0.6 6.5l17.7 30.9-17.5 29.5c-1.2 2-1.6 4.5-1.1 6.8 0.7 2.3 2.1 4.1 4.1 5.3 2 1.2 4.4 1.6 6.7 0.9 2.2-0.5 4.2-1.9 5.4-3.9l20.1-34.1q0.7-0.9 0.9-2.1 0.3-1.1 0.3-2.3 0-1.2-0.3-2.2-0.2-1.2-0.8-2.2z"/></svg>