docs+test: the young-run window in SERVER-MODE/LANES; run.test plants its link in the real drop dir

run.test.js hardcoded /tmp/agenthub-drops-<uid>, which drops left for
<data dir>/drops long ago — it passed only while an old build's folder
survived in /tmp (gone after a reboot). Full suites: server 2887/2887,
client 1250/1250.

.env.example

@@ -91,6 +91,11 @@
 # (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
@@ -131,6 +136,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

.githooks/commit-msg

@@ -1,3 +0,0 @@
-#!/usr/bin/env bash
-# commit-msg hook – runs Commitlint
-npx --no-install commitlint --edit "$1"

.gitignore

@@ -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

.husky/pre-commit

@@ -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."

AGENTS.md

@@ -8,7 +8,7 @@
 - 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`.
 
 ## Workspace stage

ARCHITECTURE.md

@@ -325,14 +325,15 @@ graph TD
 | `routes/analytics.js`     | Extended analytics — token totals, tool usage counts, daily event/session trends, agent type distribution. The client-side analytics heatmap grid is aligned to a Sunday start for correct day-of-week positioning                                                                                                                                                                                                                                                                                                                   |
 | `routes/pricing.js`       | Model pricing CRUD (list/upsert/delete) and per-session / global cost calculation with pattern-based model matching. `PUT /api/pricing` upserts a rule and accepts optional time-limited **introductory** rates (`intro_*_per_mtok` + `intro_until`): usage on/before the cutoff date prices at the intro rate, after it at the standard rate — the calculator picks the effective rate per usage day (`ratesForBucket`), so a promo like Sonnet 5's launch discount is correct before AND after the cutoff, retroactively. Intro columns are written only when the caller sends them (a standard-rate edit never disturbs a promo). Cost is computed per token bucket — keyed by (model, speed, inference_geo, service_tier) — applying fast-mode premium, US data-residency (1.1x), and Batch (0.5x) modifiers, the 5m/1h cache-write split, plus server-tool surcharges (web search $10/1k; code execution estimated by container-time with the monthly free-hours allowance; web fetch free). `attachAgentCosts`/`agentOwnCost` reuse the same calculator to price each agent's `metadata.tokens` for the per-agent `cost` on agent-list responses. Feature rates + modifier math live in `lib/pricing-constants.js`; usage normalization in `lib/token-usage.js` |
 | `routes/settings.js`      | System info (DB size, hook status, server uptime, transcript cache stats), data export as one versioned JSON bundle and matching import/restore (`POST /api/settings/import` via `server/lib/data-transfer.js` — idempotent, session-atomic, non-destructive; consolidates machines), session cleanup (abandon stale, purge old), clear all data (including the fired-alert feed and webhook delivery log; alert *rules* and webhook *targets* are preserved as user configuration), reset pricing, reinstall hooks                                                                                                                                                                                                                                                                                                                                           |
-| `routes/alerts.js`        | HTTP surface for the rules-based alerting engine: alert-rule CRUD (`GET/POST /api/alerts/rules`, `PATCH/DELETE /api/alerts/rules/:id` — rule_type is immutable after creation, config re-validated against the stored type on PATCH), the fired-alert feed (`GET /api/alerts` with `?unacked=true` + pagination, response carries `total` and `unacked` counts), and acknowledgement (`POST /api/alerts/:id/ack`, `POST /api/alerts/ack-all`, broadcasting `alert_updated`). Every rule mutation calls `invalidateRuleCache()` so the evaluation engine picks up changes immediately |
-| `lib/alerts.js`           | Rule evaluation engine for the alerting feature. Four rule types: `event_pattern` (match `event_type` / `tool_name` / `summary_contains`, optionally requiring ≥ `count` matching events within `window_minutes` — counted via a dynamically built, statement-cached SQL query), `token_threshold` (session total tokens ≥ `total_tokens`, only evaluated on token-bearing events: PostToolUse / Stop / SubagentStop / SessionEnd), `inactivity` (active session whose `updated_at` — bumped on every ingested event — is older than `minutes`), and `status_duration` (agent stuck in `working`/`waiting` with no activity for `minutes`, joined against active sessions). Event-driven types run via `evaluateEvent()` called from `routes/hooks.js` **after** the ingest transaction commits and the HTTP response is sent — alerting can never slow down or fail hook ingestion, and `evaluateEvent` is itself fully try/catch-guarded per rule. Time-based types run via `sweepTimeRules()` on a 60 s unref'd interval (same pattern as the hooks watchdog). `fireAlert()` applies per-(rule, session, agent) cooldown dedup (`cooldown_seconds`, default 300) by checking the most recent `alert_events` row for the scope, then persists and broadcasts `alert_triggered`. Enabled rules are cached in memory (hook ingest is hot) and invalidated on every CRUD mutation. `validateRuleConfig()` normalizes + validates type-specific config and is shared with the routes. After persisting and broadcasting a fired alert, `fireAlert()` hands it to `lib/webhooks.js` `dispatchAlert()` fire-and-forget (lazy-required to keep the module graph acyclic) — webhook delivery never blocks or fails alert firing |
+| `routes/alerts.js`        | HTTP surface for the rules-based alerting engine: alert-rule CRUD (`GET/POST /api/alerts/rules`, `PATCH/DELETE /api/alerts/rules/:id` — rule_type is immutable after creation, config re-validated against the stored type on PATCH), the fired-alert feed (`GET /api/alerts` with `?unacked=true` + pagination, response carries `total` and `unacked` counts), and acknowledgement (`POST /api/alerts/:id/ack`, `POST /api/alerts/ack-all`, broadcasting `alert_updated`), and the read-only dry run `POST /api/alerts/rules/preview` (`{rule_type, config, days?, cooldown_seconds?}` → what `previewRule` says it would have fired over the last `days`, 1–90, default 7). Every rule mutation calls `invalidateRuleCache()` so the evaluation engine picks up changes immediately |
+| `routes/budgets.js` + `lib/budgets.js` | Spend budgets: a budget IS an alert rule of type `budget` (CRUD through `/api/alerts/rules`). `lib/budgets.js` computes a period's bounds in the user's local time (`tz_offset` saved with the rule; day / week from Monday / month), its spend priced like `GET /api/pricing/cost` by the day tokens were spent (via `dailyTokenRows` + `costWhere`, scoped to `tool`/`lane`), and the pace projection to the period's end; `GET /api/budgets/status` lists every enabled budget with `spend`, `pct`, `projected` and the thresholds `crossed` |
+| `lib/alerts.js`           | Rule evaluation engine for the alerting feature. Six rule types — `cost_threshold` (a session's cost ≥ `usd`, on token-bearing events like `token_threshold`) and `budget` (on the sweep: each of `thresholds` % of `limit_usd` for the current `period` fires ONCE per period, deduped on `details.period_start` + `details.threshold` and bypassing the cooldown) plus the four original ones: `event_pattern` (match `event_type` / `tool_name` / `summary_contains`, optionally requiring ≥ `count` matching events within `window_minutes` — counted via a dynamically built, statement-cached SQL query), `token_threshold` (session total tokens ≥ `total_tokens`, only evaluated on token-bearing events: PostToolUse / Stop / SubagentStop / SessionEnd), `inactivity` (active session whose `updated_at` — bumped on every ingested event — is older than `minutes`), and `status_duration` (agent stuck in `working`/`waiting` with no activity for `minutes`, joined against active sessions). Event-driven types run via `evaluateEvent()` called from `routes/hooks.js` **after** the ingest transaction commits and the HTTP response is sent — alerting can never slow down or fail hook ingestion, and `evaluateEvent` is itself fully try/catch-guarded per rule. Time-based types run via `sweepTimeRules()` on a 60 s unref'd interval (same pattern as the hooks watchdog). `fireAlert()` applies per-(rule, session, agent) cooldown dedup (`cooldown_seconds`, default 300) by checking the most recent `alert_events` row for the scope, then persists and broadcasts `alert_triggered`. Enabled rules are cached in memory (hook ingest is hot) and invalidated on every CRUD mutation. `validateRuleConfig()` normalizes + validates type-specific config and is shared with the routes. After persisting and broadcasting a fired alert, `fireAlert()` hands it to `lib/webhooks.js` `dispatchAlert()` fire-and-forget (lazy-required to keep the module graph acyclic) — webhook delivery never blocks or fails alert firing |
 | `routes/webhooks.js`      | HTTP surface for universal webhook targets: target CRUD (`GET/POST /api/webhooks`, `PATCH/DELETE /api/webhooks/:id` — `type` is immutable after creation), a redacted provider catalog (`GET /api/webhooks/providers`, drives the UI form), a synchronous test probe (`POST /api/webhooks/:id/test` — always 200, the `ok` flag carries the downstream delivery result), and a per-target delivery log (`GET /api/webhooks/:id/deliveries`). Validation is registry-driven: required URL (per provider), per-provider config fields, https enforcement, generic-family secret/headers. **Security**: target URLs are masked (host + last 4 chars) and secret config fields + custom-header values are redacted in every response — full URLs, signing secrets, and credentials (routing keys, api keys, bot tokens) are stored server-side and never leave the server. PATCH uses "set-flag" semantics (omit `url`/`secret`/`headers`/`config` to leave unchanged); `config` is merged over the existing config so one field can change without re-sending secrets. Every mutation calls `invalidateWebhookCache()` |
 | `lib/webhook-providers.js`| Declarative registry of the 14 first-class providers (+ generic). Each entry declares a `family` (`chat` / `api` / `generic`), a payload `format`ter, URL resolution (`urlFrom(config)` for Telegram/Opsgenie that derive the endpoint, `defaultUrl` for PagerDuty, or a user-supplied URL), optional `authFrom(config)` headers (Opsgenie GenieKey), and the credential `fields` the UI renders + the route validates. Formatters emit each platform's native body: Slack Block Kit, Discord embed, Teams Adaptive Card wrapped in the Power Automate Workflows `{ type: "message", attachments: [...] }` envelope (the legacy O365-connector MessageCard transport was retired May 2026), Google Chat text, Mattermost/Rocket.Chat Slack-style attachments, Telegram sendMessage (HTML), PagerDuty Events API v2 (with `dedup_key`), Opsgenie Alert API, Splunk On-Call/VictorOps, and the generic `{ event, alert }` envelope. A provider may also declare `verifyResponse(body)` to veto a 2xx that actually signals failure (Splunk On-Call returns 200 with `result:"failure"`). `publicProviders()` returns the redacted catalog. Adding a provider = one registry entry + a formatter — no route or delivery changes |
 | `lib/webhooks.js`         | Universal webhook delivery engine driven by the provider registry. `buildRequest()` resolves the URL, formats the provider-native payload, and assembles headers (provider auth headers + generic-family custom headers + optional HMAC-SHA256 signature via `X-Webhook-Signature` / `X-Webhook-Timestamp`). `dispatchAlert()` fans a fired alert out to every enabled, in-scope target (optional per-rule scoping via `rule_ids`); each `deliver()` POSTs with an `AbortController` timeout and bounded retry/backoff (retries transport errors / 429 / 5xx, never other 4xx) and records the attempt-chain outcome in `webhook_deliveries` (pruned to the newest 2000 rows). Delivery is detached and fully fail-safe — it never throws into the alert path. Enabled targets are cached like alert rules; tunables (`WEBHOOK_TIMEOUT_MS`, `WEBHOOK_MAX_ATTEMPTS`, `WEBHOOK_RETRY_BASE_MS`) are env-overridable. `sendTest()` awaits a synthetic delivery for the test endpoint |
 | `routes/workflows.js`     | Aggregate workflow visualization data (agent orchestration graphs, tool transition flows, collaboration networks, workflow pattern detection, model delegation, error propagation, concurrency timelines, session complexity metrics, compaction impact). Accepts `?status=active\|completed` query parameter to filter all data by session status and `?sections=a,b` to compute only those parts. The `GET /` bundle itself lives in `lib/workflow-stats.js` and runs in the read worker (`lib/read-pool.js`). `GET /api/workflows/skill-usage` reports per-skill and per-plugin call counts, counting `PreToolUse` rows only so a call is not double-counted against its `PostToolUse` twin. Per-session drill-in endpoint with agent tree, tool timeline, and event details |
 | `lib/workflow-stats.js`  | The eleven `GET /api/workflows` aggregations as pure reads over a passed-in connection (`computeWorkflowData(conn, status, sections)`), so they run in the read worker. `stats.topFlow` is the head of `toolFlow.transitions`: tool pairs come from one `LEAD() OVER (PARTITION BY session_id ORDER BY id)` pass — never a correlated `MIN(id) … id > ?` per event, which is quadratic in a session's size |
-| `lib/read-pool.js`        | Heavy read-only jobs off the event loop: one worker thread with its own `query_only` connection (same driver order as `db.js`), identical in-flight calls shared, a job past `AGENTHUB_READ_TIMEOUT_MS` (60 s) refused `EREADTIMEOUT` and its worker replaced, inline when `AGENTHUB_READ_WORKER=0` or a worker cannot start. Add a job to `JOBS` to move another aggregate there |
+| `lib/read-pool.js`        | Heavy read-only jobs off the event loop: one worker thread with its own `query_only` connection (same driver order as `db.js`), identical in-flight calls shared, a caller's `maxAgeMs` reusing a result that young (`/api/workflows` 30 s, `/api/analytics`'s events scans 10 s — args are the key, so a member's scoped result is never shared), a job past `AGENTHUB_READ_TIMEOUT_MS` (60 s) refused `EREADTIMEOUT` and its worker replaced, inline when `AGENTHUB_READ_WORKER=0` or a worker cannot start. Add a job to `JOBS` to move another aggregate there. The server's WAL checkpoint (`walCheckpoint`, every `DASHBOARD_WAL_CHECKPOINT_MS`, default 5 s) also runs here, on a second writable connection of the worker: the main connection sets `wal_autocheckpoint = 0`, so no hook's `COMMIT` pays for a checkpoint; a failed checkpoint turns the automatic one back on |
 | `lib/transcript-cache.js` | Stat-based JSONL transcript cache with incremental byte-offset reads. Shared between `hooks.js` (token extraction on every event) and the periodic compaction scanner (`index.js`). Extracts tokens, compaction entries, API errors (`isApiErrorMessage` + raw error responses), turn durations (`system` subtype `turn_duration`), thinking block counts, usage extras (service_tier, speed, inference_geo), user-interrupt markers (the transcript `[Request interrupted by user]` entry / `interruptedMessageId` field — surfaced as `pendingInterrupt`, computed from transcript ordering: latest interrupt vs latest real turn activity, both on Claude Code's clock), and the latest session title — `custom-title` (`/rename`, `claude -n`, picker Ctrl+R) and `ai-title` (auto / plan-accept), append-only so the last value wins, carried through both full and incremental reads — plus the session's **first user prompt** (`firstUserMessage`: tool-result, meta/caveat, slash-command plumbing, compact-summary, and interrupt entries skipped; whitespace-collapsed, capped at 500 chars; first value wins across incremental reads), used as a fallback descriptor for placeholder-named sessions/agents. Uses `(path, mtime, size)` cache key — unchanged files return cached results instantly, grown files only parse new bytes, shrunk files (compaction) trigger full re-read. Each cache entry stores **only** `{mtimeMs, size, bytesRead, result}` — the previous shape that duplicated every growable array at both the top level and inside `result` is gone, halving steady-state memory per entry. Per-entry growable arrays (`turnDurations`, `errors`, `compaction.entries`, `usageExtras.*`) are bounded to `TRANSCRIPT_CACHE_MAX_ARRAY_LEN` (default `1000`, tail-kept) — older items remain in the `events` table thanks to hook dedup, so the cap only affects the in-memory view. Trimming runs both during parse (when an array reaches `2 * MAX_ARRAY_LEN`, amortized O(N)) and at finalize, so even a fresh full-file parse on a multi-day session cannot accumulate an unbounded transient before returning. **Chunked sync byte-stream reader** (`_streamRange`, 4 MiB chunks split on `0x0A` bytes — safe across UTF-8 multibyte sequences — with a growable per-line byte buffer capped at 64 MiB) replaces the previous `readFileSync("utf8")` so transcripts larger than V8's max JS string length (~512 MiB on 64-bit Node 20) parse without aborting Node with `FATAL ERROR: v8::ToLocalChecked Empty MaybeLocal`. Both full and incremental reads share the same line-level state machine (`_initParseState` / `_consumeLine` / `_finalizeState`). LRU eviction caps at 200 entries. Entries evicted on SessionEnd and abandoned session cleanup |
 | `lib/session-liveness.js` | Process-liveness probe for the watchdog's dead-session reap. `probeLiveCwds()` enumerates running `claude` CLI processes (`ps -Ao pid=,args=`, then `lsof -a -p <pids> -d cwd -Fn` on macOS or `/proc/<pid>/cwd` on Linux) and returns the set of their working directories; `isClaudeCommand()` matches the bare binary and `node`/`bun`-launched shims while rejecting lookalikes (`claude-mem`, `Claude.app`). Fail-safe by contract: returns `available: false` (callers must change nothing) on Windows, inside containers (reuses `isInsideContainer` from `scripts/install-hooks.js` — host processes are invisible there, so an empty list would lie), on `ps`/`lsof` failure, or when `DASHBOARD_LIVENESS_PROBE=0` |
 | `bin/agenthub.js` | Dependency-free umbrella CLI (`agenthub <command>`) exposing the full dashboard surface in the terminal: monitoring (health / stats / kanban / tail via short-interval event polling), data browsing (sessions, per-session detail with an indented agent tree + cost + recent events, agents, events), insights (analytics, workflow intelligence, dynamic Workflow-tool runs, per-model cost), alerts + rules + webhook test probes, pricing CRUD, imports (rescan / scan-path), and administration (doctor, info, export, cleanup, reinstall-hooks, clear-data). Linked globally by `npm run setup` via a fail-soft `npm link` (`link-cli` script). Discovers the live server through `server/lib/server-info.js` (`~/.claude/.agenthub.json`, PID-liveness-checked) with `CLAUDE_DASHBOARD_PORT` / `DASHBOARD_PORT` env overrides and a 4820 fallback; renders a full terminal UI — box-drawn width-fitted tables with right-aligned numeric columns, status icons, inline bar charts (stats / analytics / cost), `├─`/`└─` agent trees, and a TTY spinner for `start` — whose ANSI styling degrades to plain text when piped (`--no-color` / `NO_COLOR` / `FORCE_COLOR` / `AGENTHUB_COLOR` respected); the one destructive command (`clear-data`) refuses to run without `--yes`. Server lifecycle: `agenthub status` shows a ●/○ up/down indicator and `agenthub start` boots a detached production server (waits for /api/health, logs to `data/agenthub-server.log`). `agenthub repl` (aliases `shell` / `i`) opens an interactive shell — a readline prompt with tab-completion (commands / subcommands / flags), persisted arrow-key history (`data/.agenthub_repl_history`), and a live server-status prompt; each entered line runs as a short-lived child `agenthub` process (via `runCommand` dispatch), so an offline refusal or a blocking `tail` cannot take the shell down, and piped input runs each line in order then exits at EOF. When the server is down, read-only commands (sessions / session / agents / events / kanban / stats / pricing list / alerts list / rules / export / doctor) fall back to direct SQLite reads of `data/dashboard.db` under a ⚠ Offline-mode banner — the connection is opened without SQLite readonly mode so a live WAL stays visible, and is SELECT-only by construction — while server-only commands (tail, analytics, workflows, runs, cost, mutations) refuse with the specific reason |
@@ -351,8 +352,8 @@ graph TD
 | `server/lib/archive.js`     | Safe archive extraction: `.zip` via `adm-zip`, `.tar`/`.tar.gz`/`.tgz` via `tar`, plain `.gz` via `zlib` in streaming mode. Every entry is validated through `safeJoin` which rejects absolute paths and `..` traversal before any bytes are written. Enforces a hard extraction cap (`MAX_EXTRACT_BYTES`, default 4 GB, tunable via `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES`) with `ExtractionLimitError` surfaced as HTTP 413 from the upload route — defense against zip/tar/gzip bombs. Also provides `detectKind` for filename-based dispatch and `mkTempDir`/`rmTempDir` helpers |
 | `server/lib/remote-sync.js` | **Remote Data Sources** — live remote/multi-machine data collection over SSH. Mirrors the remote's `~/.claude/projects` via **scp** (or `wsl.exe` + `tar` for WSL-hosted Claude on Windows SSH) into a **sandboxed per-source staging dir** under the data dir, then feeds it through the **same** importer used for local history (`importFromDirectory` from `scripts/import-history.js`) and tags every imported session with the source id (`sessions.source`). Also runs the connectivity probe behind the test route. Auth **defers entirely to the host SSH stack** (ssh-agent / `~/.ssh/config` / identity file) — **no secrets are ever stored**; every shell-out uses `execFile`/`spawn` argument arrays (never a shell string), and `StrictHostKeyChecking` is left at its SSH default. Background poller `DASHBOARD_REMOTE_SYNC_MS` (default 15000); add/re-enable triggers immediate pull. Sync timeout `DASHBOARD_REMOTE_SYNC_TIMEOUT_MS` (default 600000); connectivity-test timeout `DASHBOARD_REMOTE_TEST_TIMEOUT_MS` (default 15000). Broadcasts `remote_source.status`, `remote_data.updated`, and per-session `session_created`/`session_updated` on successful sync. After each pull, `reconcileRemoteSessionStatus` sets each source session's live status from the mirror — newest JSONL event timestamp within `DASHBOARD_REMOTE_ACTIVE_WINDOW_MS` (default 600000 = 10 min) ⇒ `active`, otherwise `completed`. Remote sessions get no live hooks and are excluded from every local liveness/stale heuristic (all gated on `source = 'local'`), so this reconciliation is the sole owner of their active/completed lifecycle |
 | `server/routes/remote-sources.js` | HTTP surface for **Remote Data Sources**: `GET /api/remote-sources` (list), `POST /api/remote-sources` (create), `PATCH /api/remote-sources/:id`, `DELETE /api/remote-sources/:id` (`?purge=true` also deletes that source's imported sessions), `POST /api/remote-sources/:id/test` (SSH connectivity probe), and `POST /api/remote-sources/:id/sync` (on-demand pull). Delegates the pull/validation to `remote-sync.js`; broadcasts `remote_source.status` on every transition |
-| `server/lib/source-filter.js` | Parses the optional `?sources=` query param (comma-separated source ids) into SQL predicates + bind params, shared by the data endpoints (`GET /api/sessions`, `/api/events`, `/api/agents`, `/api/stats`, `/api/analytics`) so a client **data-scope** selection narrows every query consistently. No filter → the existing unscoped queries run unchanged |
-| `server/lib/scoped-stats.js` | Source-scoped variants of the stats/analytics aggregates, used **only** when a `?sources=` scope filter is active — the unscoped fast paths in `routes/stats.js` / `routes/analytics.js` are untouched when no scope is set |
+| `server/lib/source-filter.js` | Parses the optional `?sources=` query param (comma-separated source ids) and `?tool=` (an AI tool id; `parseScope` folds both into one predicate over `sessions`) into SQL predicates + bind params, shared by the data endpoints (`GET /api/sessions`, `/api/events`, `/api/agents`, `/api/stats`, `/api/analytics`) so a client **data-scope** selection narrows every query consistently. No filter → the existing unscoped queries run unchanged |
+| `server/lib/scoped-stats.js` | Scoped variants of the stats/analytics aggregates, used **only** when a `?sources=` or `?tool=` scope filter is active — the unscoped fast paths in `routes/stats.js` / `routes/analytics.js` are untouched when no scope is set |
 | `lib/cc-discovery.js`     | Read-only discovery of every Claude Code config surface for the Config Explorer page. Pure file reads; never writes. Surfaces: skills (`<root>/skills/<name>/SKILL.md`), subagents (`<root>/agents/*.md`), slash commands (`<root>/commands/*.md`), output styles (`<root>/output-styles/*.md`), plugins (`<CLAUDE_HOME>/plugins/installed_plugins.json` joined with `enabledPlugins` in settings + per-plugin `contributes` counts **and** `contributes.items`, which names every skill / subagent / command / output style the plugin ships — each surface read from the conventional install subdirectory *and* from whatever path `plugin.json` declares for that key, with declared paths outside the plugin's own install dir dropped by `isUnder()`, so a plugin that lists its commands explicitly and keeps `commands/` empty no longer reports zero + `plugin.json` metadata), marketplaces (`known_marketplaces.json` enriched with each `marketplace.json`), MCP servers (top-level + per-project from `~/.claude.json`), hooks (across user / project / project-local settings.json), keybindings (`<CLAUDE_HOME>/keybindings.json`), statusline config + `statusline.py` / `statusline-command.sh` content, hook scripts dir (`<CLAUDE_HOME>/hooks/`), settings (with secret-key redaction matching `/token\|secret\|password\|api[_-]?key\|auth/i`), memory (`CLAUDE.md` at user + project **plus** the per-project file-based auto-memory store — every `*.md` under `~/.claude/projects/<slug>/memory/`, returned as `scope:"auto-memory"` items carrying `project`, `name`, `isIndex`, and parsed `frontmatter`, so a `MEMORY.md` index and one file per remembered fact, often 100+, all surface). Path containment via `isUnder()` — every read must resolve under CLAUDE_HOME, project `.claude/`, or be a project CLAUDE.md. 256 KB read cap. Minimal YAML frontmatter parser handles `key: value` + quoted strings + indented continuation lines |
 | `lib/cc-mutate.js`        | Create / overwrite / delete for the **low-risk text-file surfaces only** (skills, subagents, slash commands, output styles, memory — including the per-project file-based auto-memory store, mutated via `scope: "auto-memory"`, `type: "auto-memory"`, `project`, `name`, with its backups landing in `<memory-dir>/.cc-config-backups/auto-memory/`), plus `writeKeybindings()` for the structured `keybindings.json` editor (read-modify-write that preserves top-level metadata, rejects duplicate contexts/keys, and backs up to `<CLAUDE_HOME>/cc-config-backups/keybindings/`). Plugins, MCP, hooks-in-settings, and `settings.json` files are NEVER written from here — they have concurrent-write races with the live Claude Code CLI. Every mutation creates a timestamped backup at `<root>/cc-config-backups/<type>/<base>.<ISO>.bak[.dir]` BEFORE the change — backups land outside the directories Claude Code scans, so a deleted skill cannot resurface as a backup-named one. Writes are atomic: temp file in same dir → fsync → `renameSync`. Tmp removed on every failure path. Skill dirs are backed up whole (preserving bundled assets) before recursive removal. Strict `name` regex (`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`), 256 KB content cap, double-checked path containment via `isUnder()` |
 | `lib/cc-reload.js`        | Types `/reload-plugins` / `/reload-skills` into the Claude Code sessions the dashboard already has open, over `tmux send-keys` (reusing `tmux.js`'s `sendText`). Both slash commands are scoped BY CLAUDE CODE to the session that runs them, so a session cannot be reloaded from the outside and no background process can do it on a session's behalf — typing into a live pane is the only real mechanism. Deliberately spawns NO `claude` process: a one-shot `claude -p "/reload-plugins"` would reload only its own short-lived session, exit, and leave a junk session in the dashboard's history, so this module creates no sessions at all. Skips panes sitting at a shell prompt (the text would run as a shell command) and addresses `claude` lanes only, since Codex has no such command. Sends to a busy pane on purpose — tmux queues the keystrokes into the REPL's input buffer, so a late reload still lands, where skipping busy panes would leave exactly the sessions in active use running stale code. The command set is a fixed constant, never caller-supplied: a pane's stdin is an arbitrary-code boundary. Never throws |
@@ -367,12 +368,13 @@ graph TD
 | `lib/codex-hooks.js`     | AgentHub's hooks in Codex's `$CODEX_HOME/hooks.json`, installed/removed only on a click (`GET/POST/DELETE /api/settings/codex-hooks`): one group per event through the stable forwarder `$CODEX_HOME/agenthub-hook.sh`, whose content `refreshScript()` rewrites at every start; trust is read from Codex's `config.toml`, never written. See **Codex hooks** under Codex Lane Status, Sessions and Hooks. |
 | `lib/antigravity-home.js` | Where agy keeps its data: `~/.gemini` (`AGENTHUB_GEMINI_DIR` overrides it), the CLI's `antigravity-cli/` under it. agy has no home override of its own. |
 | `lib/antigravity-usage.js` | Antigravity CLI sessions and tokens from agy's `conversations/<id>.db` (read-only, every `DASHBOARD_ANTIGRAVITY_POLL_MS`): protobuf `ModelUsageStats` per `gen_metadata` row, the workspace from `trajectory_metadata_blob`, name/start from the transcript. Also sets a quiet session's lane idle. See **Antigravity Sessions and Hooks**. |
+| `lib/cursor-usage.js` | Cursor sessions (no tokens: Cursor's transcripts carry none) from `~/.cursor/projects/*/agent-transcripts/<id>/<id>.jsonl`, every `DASHBOARD_CURSOR_POLL_MS`. See **Cursor Sessions**. |
 | `lib/antigravity-hooks.js` | AgentHub's named hook `agenthub` in `~/.gemini/config/hooks.json` (`GET/POST/DELETE /api/settings/antigravity-hooks`): PreInvocation, PostToolUse and Stop through the stable forwarder `~/.gemini/config/agenthub-hook.sh`, which answers `{}`. Never PreToolUse. |
 | `routes/codex-config.js`  | HTTP surface for the Codex Config panel. Read endpoints for every surface (skills, agents, rules, memory, config, mcp, plugins, marketplaces, file, overview) plus mutation endpoints (`PUT /file`, `DELETE /file` delegating to `codex-mutate.js`; `POST /mcp/{add,remove}`, `/plugins/action`, `/marketplaces/{add,action}` delegating to `codex-cli.js`), plus `GET /backups`. Every successful mutation broadcasts `codex_config_changed` over the WebSocket so an open Codex settings tab refetches without polling. All errors return structured `{error: {code, message}}` shapes |
 | `lib/tmux.js`             | Wrapper around tmux CLI for session management. `createSession(sessionName, cwd)` creates a new tmux session in the specified working directory. `sendCommand(sessionName, command)` sends a command into the session. `killSession(sessionName)` terminates the session. `listSessions()` returns all active sessions. Session management is the foundation for the PTY transport layer |
 | `lib/pty-run.js`          | PTY lifecycle for tmux-backed runs. Manages one tmux session per lane, named `agenthub-lane-<lane.id>`. Exports `startRun()` to create/attach a session and return a `runId` opaque handle; internally uses tmux to manage the pseudoterminal. Spawned `claude` processes run inside the session and fire the dashboard's hooks like any other CLI session, so they show up in `/api/sessions`, the analytics, the Kanban board, and the Workflows page automatically. The PTY frames (terminal input/output deltas) are streamed to the client over `/ws-pty/:runId` (see `server/websocket.js`) at binary frame granularity rather than as JSON envelopes; the client's xterm.js terminal widget renders these raw PTY updates live. Every spawn also mirrors itself into `dashboard_runs` (cwd, model, prompt preview, `resume_session_id`, lane id, start time) — that row is the ONLY source `publicRun` has for those fields, since the handle itself is recomputed from tmux on every read, so a dropped insert renders as a live run with no cwd, model or start date. `mode` is NOT NULL in that table and `recordRun` swallows insert errors by design, which is why this module passes a literal `"interactive"` rather than null. **Create-or-adopt has one refusal:** a pane already running an agent is adopted silently only when the request asked for nothing but a pane — a `resumeSessionId` or an initial prompt cannot be typed over a live agent, so it throws `ERUNLIVE` (409) rather than reporting a resume that never spawned |
 | `lib/pty-attach.js`       | Client-side PTY attachment via WebSocket. Establishes a `/ws-pty/:runId` connection, receives binary PTY frames, and feeds them to an xterm.js terminal instance. Handles reconnection, resize events (sending `TIOCSWINSZ` ioctl to the tmux pane), and cleanup on disconnect. A single tmux session can have many simultaneous PTY clients (browser Workspace, `agenthub lanes shell` CLI, etc.), all synced live The server side (`server/lib/pty-attach.js`) runs `tmux attach` with the LIVE tmux server's own binary (`/proc/<tmux.serverPid()>/exe`, else `tmux` on PATH): a tmux upgraded while its server runs leaves a newer client on PATH that the old server refuses with `open terminal failed: not a terminal`. |
-| `routes/run.js`           | HTTP surface for the tmux+PTY Run feature. **Same-origin guard** on every route — browser requests must come from a localhost-ish Origin (`localhost`, `127.0.0.1`, `::1`, `0.0.0.0`); missing-Origin (curl/CLI) requests pass. When `DASHBOARD_TOKEN` is configured it is **also** required on these routes (same as the rest of `/api/*`). `GET /api/run` lists all live runs (computed fresh from tmux state via `tmux list-sessions`). `GET /api/run/tmux` reports whether `tmux` is installed and on PATH (required for the feature to work). `GET /api/run/binary` probes whether `claude` is on `PATH`. `GET /api/run/cwds` suggests cwds (dashboard + home + recent from sessions table). `GET /api/run/history?laneId=...` returns persisted run history, optionally scoped to one lane. `GET /api/run/files?cwd=&q=` powers the Workspace page's `@`-file autocomplete: scoped fuzzy search inside `cwd` skipping `node_modules`, `.git`, `dist`, `build`, `.next`, `.cache`, `coverage`, `vendor`, etc., capped result count, ranked by basename match. `POST /api/run/drop-image` saves an image dropped on the terminal (raw body, four image types, random name under `<tmpdir>/agenthub-drops-<uid>/`) and returns the path the terminal pastes. `POST /api/run` requires `laneId` in the body and starts/attaches a tmux-backed run. `GET /api/run/:id` returns the run handle. `DELETE /api/run/:id` kills the tmux session (sends SIGTERM to the pane, escalates to SIGKILL after 5 s). The PTY frames are streamed to the client over `/ws-pty/:runId` as binary frames (not JSON), rendering a real interactive terminal in xterm.js on the Workspace page. `tmux` must be installed on the dashboard server's machine (same as better-sqlite3's native-module requirements) |
+| `routes/run.js`           | HTTP surface for the tmux+PTY Run feature. **Same-origin guard** on every route — browser requests must come from a localhost-ish Origin (`localhost`, `127.0.0.1`, `::1`, `0.0.0.0`); missing-Origin (curl/CLI) requests pass. When `DASHBOARD_TOKEN` is configured it is **also** required on these routes (same as the rest of `/api/*`). `GET /api/run` lists all live runs (computed fresh from tmux state via `tmux list-sessions`). `GET /api/run/tmux` reports whether `tmux` is installed and on PATH (required for the feature to work). `GET /api/run/binary` probes whether `claude` is on `PATH`. `GET /api/run/cwds` suggests cwds (dashboard + home + recent from sessions table). `GET /api/run/history?laneId=...` returns persisted run history, optionally scoped to one lane. `GET /api/run/files?cwd=&q=` powers the Workspace page's `@`-file autocomplete: scoped fuzzy search inside `cwd` skipping `node_modules`, `.git`, `dist`, `build`, `.next`, `.cache`, `coverage`, `vendor`, etc., capped result count, ranked by basename match. `POST /api/run/drop-image` saves an image dropped on the terminal (raw body, four image types, random name under `<data dir>/drops/` (a member's `~/.agenthub/handoff/drops/` under S3)) and returns the path the terminal pastes. `POST /api/run` requires `laneId` in the body and starts/attaches a tmux-backed run. `GET /api/run/:id` returns the run handle. `DELETE /api/run/:id` kills the tmux session (sends SIGTERM to the pane, escalates to SIGKILL after 5 s). The PTY frames are streamed to the client over `/ws-pty/:runId` as binary frames (not JSON), rendering a real interactive terminal in xterm.js on the Workspace page. `tmux` must be installed on the dashboard server's machine (same as better-sqlite3's native-module requirements) |
 | `routes/lanes.js`         | Durable-lane API. `POST /api/lanes/worktree`, `PATCH /api/lanes/:id`, destructive actions, and `DELETE /api/lanes/:id` use the Run route's same-origin guard. Worktree provisioning validates an absolute source git repository, persists a managed lane as `provisioning`, returns `202`, then uses the per-lane lock to resolve the base and add the worktree. Completion broadcasts the existing `lane_update` payload as `idle`; a git failure leaves a row that the non-destructive delete route can forget. `GET /api/lanes/:id/preflight?action=reset\|remove\|purge` produces counted confirmation facts. Confirmed `POST /:id/{reset,remove,purge}` actions require a complete `expect`, run under the same lock, kill a recorded run and wait for the spawner's actual child-exit timestamp (or return `500 ERUNTIMEOUT` before git), clear `run_id`, reject changed facts with `409 ESTALE` including expected/current diagnostics, and require `force` for unpushed managed reset/remove work. Reset and managed removal call the worktree's independent managed-kind, realpath-within-`LANES_ROOT`, and listed-worktree guard; adopted reset is refused, while adopted remove only forgets its row and never modifies its directory, and a managed lane whose directory was deleted by hand takes a prune path that still enforces the managed-kind and inside-`LANES_ROOT` checks. `start` returns `409 ERUNLIVE` rather than overwriting a live `run_id` and orphaning its child. `kind`, `source_repo`, `slug`, `base_branch`, `slot` and `ports` are not patchable — provisioning writes them through `lanesLib.setProvisioningFacts`. Worktree provisioning also runs `lane-runtime.js:provisionLane` (A2) when the repo declares a `.agenthub/profile` — seed `.env`, `bootstrap`, create the database, migrate, seed — before the lane reports `idle`; `reset`/`remove` likewise call `resetLaneData`/`removeLaneData`, with `reset` accepting a body `keepDb: true` to skip the whole drop-recreate-migrate-reseed block. The runtime routes (`GET /:id/runtime`, `POST /:id/up`, `POST /:id/down`, `POST /:id/hook/:name`, `GET /:id/logs/:svc`) are registered **before** the `/:id/:action` catch-all so `up`/`down` are not swallowed as unknown actions, and are deliberately kept out of it: that catch-all drives a lane's Claude run, these drive the application the lane is working on. `GET /api/lanes/pipeline-stats` aggregates per-node pass counts over every lane and every archived feature. The git surface (#34/#35) sits under `/:id/git/*`, again before the catch-all: `GET /:id/git/changes` (ranges `work`/`branch`/`commit`, with `context`), `/:id/git/log`, `/:id/git/file`, `/:id/git/ls`, `/:id/git/tree` and `/:id/git/branches` are read-only and unguarded like `/:id/git`, while `POST /:id/git/:action` is same-origin guarded and runs under the lane lock — and its per-file actions (`stage`, `unstage`, `discard`) accept only paths `git status` reports as changed, with `discard` additionally requiring `confirm: true`. |
 | `lib/ports.js`            | TCP probing for runtime allocation. `isListening(port)` connects rather than binds (binding races with the hook about to bind, and says nothing about a listener held by another user); a connect timeout counts as occupied. `listenerPids(port)` shells to `lsof`, falls back to `ss`, and returns `[]` with a one-time warning when neither exists — a missing tool must never fail a lane operation |
 | `lib/lane-slots.js`       | Slot and port allocation — the numbering Shipyard gets free from fixed `lane1..lane9` directories and AgentHub, keyed by `cwd`, must allocate. `allocateSlot` takes the lowest free of `LANE_MAX_SLOTS` (default 9) under the per-lane lock, with a partial unique index on `lanes.slot` as the backstop; allocation is **lazy**, so a lane that is only watched never consumes one. `releaseSlot` runs on remove but never on reset (moving a lane's ports mid-feature is a silent failure, not a fresh start). `resolvePorts` prefers `PORT_BASE_<name> + slot`, then steps `+100` at a time so the last digit still reads as the slot, skipping anything listening, recorded by another lane, or already taken in the same boot. `slotDirs` puts run/log state under `LANES_ROOT/.state/lane<slot>/` — outside the worktree, because `reset`'s `git clean -fd` would otherwise sweep live pid files. `dbName`/`dataFacts` (A2) derive the same kind of slot-based fact one layer up: database name, `DATABASE_URL`/`TEST_DATABASE_URL`, a Redis logical index, and the upload directory — each `null` when its owning profile declaration (`DB_PREFIX`, `REDIS`, `UPLOAD_SUBDIR`) is absent |
@@ -384,7 +386,7 @@ graph TD
 | `lib/lane-services.js`    | (A2) `ensureDatabase`/`dropDatabase` call the profile's `db-create`/`db-drop` hooks — AgentHub stays stack-agnostic on purpose. A state-dir marker file tracks whether a slot's database was already created, since a plain `createdb` can't be re-run safely and AgentHub can't assume the hook is idempotent; this is also how `upLane` knows to seed only a freshly-created database. `dropDatabase` asserts the lane is `managed` and that the name being dropped is one this lane's own slot actually derives (itself or its `_test` sibling) before spawning anything |
 | `lib/lane-features.js`    | (B) Per-feature state and archive. `activateFeature` archives the lane's current active feature (if different) and restores the target's saved stage onto the live `lanes` row — the row stays the one live view every other reader already uses. `canonicalizeSlug` is a DELIBERATELY separate rule from `worktree.js:slugify` (drops a leading `feat/`, keeps `[A-Za-z0-9._-]`, does not lowercase) — the two must never be conflated. `clearLane` (`lib/lanes.js`) archives the active feature (if any) before resetting; a lane that never activated one is unaffected |
 | `lib/git-diff.js`         | (#34/#35) Reads a lane's code changes as structured hunks for the Workspace Changes panel — `work` (HEAD vs the working tree, untracked files included), `branch` (`<base>...HEAD`) or `commit` (one sha), at a caller-chosen `context` (default 3, clamped to 5000, which is how the viewer expands a diff towards the whole file). Also the four reads behind History, the whole-file view, quick-open and the file explorer: `listCommits`, `readFileAt` (the `work` revision is realpath-confined to the lane; anything else goes through `git show`), `listPaths` and `listTree` (both `git ls-files`, so `.gitignore` is honoured without a skip-list). Read-only, argv-only through `worktree.js:git()`. An untracked file's patch is SYNTHESIZED from the file itself rather than fetched with `git diff --no-index`, which exits non-zero on a difference and would read as a failure. Three caps (300 files, 200 KB per file, 1 MB per full read) keep a lane mid-build from shipping megabytes of patch into a browser; a cap that bit sets `truncated` |
-| `lib/git-ops.js`          | (#34) The git WRITES a lane offers: `fetch`, `pull`, `push`, `stage`, `unstage`, `discard`, `stage-hunk`/`discard-hunk` (one hunk, matched by its `@@` line against a fresh diff — or one `block`, a run of +/- lines inside it, the others folded into context by `onlyBlock` in `git-diff.js` (#50); `discard-hunk` needs `confirm:true`), `commit` (everything, or `only:"staged"`), `switch`, `branch-create` (never switches) and `branch-delete` (`-d`, refusing `main`/`master`/`development`/`develop`, the current branch and one another worktree holds), `publish` (`remote add origin -- <url>` + `push -u origin HEAD`, only when the repo has NO remote and a commit; the one write whose destination comes from the request, so the URL is allowlisted by `validateRemoteUrl` — `https://` without userinfo, `ssh://`, scp-like `user@host:path` — and `origin` is removed again when the push fails), and `merge`/`resolve`/`merge-commit`/`merge-abort` (issue #45: a named branch into a clean repo-root lane, conflicts resolved per file, abort behind `confirm:true`). A caller-supplied path is validated against `git status` before it reaches an argv, so only a path git already reports as changed is reachable; `discard` — the one irreversible action — additionally requires `confirm: true`. No rebase, reset or stash, because a dashboard button is the wrong place to start an operation whose recovery needs a terminal (`reset` stays behind worktree.js's three-check destroy guard). `pull` is ALWAYS `--ff-only` and `switch` refuses a dirty tree, so neither can invent a merge commit or a conflict underneath a running agent; `push` pushes `HEAD`, never a branch name from the request. Network actions carry a 60s timeout |
+| `lib/git-ops.js`          | (#34) The git WRITES a lane offers: `fetch`, `pull`, `push`, `stage`, `unstage`, `discard`, `stage-hunk`/`discard-hunk` (one hunk, matched by its `@@` line against a fresh diff — or one `block`, a run of +/- lines inside it, the others folded into context by `onlyBlock` in `git-diff.js` (#50); `discard-hunk` needs `confirm:true`), `commit` (everything, or `only:"staged"`), `switch`, `branch-create` (never switches) and `branch-delete` (`-d`, refusing `main`/`master`/`development`/`develop`, the current branch and one another worktree holds), `publish` (`remote add origin -- <url>` + `push -u origin HEAD`, only when the repo has NO remote and a commit; the one write whose destination comes from the request, so the URL is allowlisted by `validateRemoteUrl` — `https://` without userinfo, `ssh://`, scp-like `user@host:path` — and `origin` is removed again when the push fails), and `merge`/`resolve`/`merge-commit`/`merge-abort` (issue #45: a named branch into a clean repo-root lane, conflicts resolved per file, abort behind `confirm:true`), `cherry-pick`/`revert` (a non-merge commit by sha, same guards and conflict flow — `merge-commit`/`merge-abort` finish whichever of the three is open, `operationInProgress` in worktree.js), and `undo-commit` (`reset --soft HEAD~1`, `confirm:true`) / `amend`, both refused once a remote-tracking branch holds HEAD (`EPUSHED`). A caller-supplied path is validated against `git status` before it reaches an argv, so only a path git already reports as changed is reachable; `discard` — the one irreversible action — additionally requires `confirm: true`. No rebase, hard reset or stash, because a dashboard button is the wrong place to start an operation whose recovery needs a terminal (a hard `reset` stays behind worktree.js's three-check destroy guard; `undo-commit`'s soft reset moves only an unpushed branch tip and keeps every change staged). `pull` is ALWAYS `--ff-only` and `switch` refuses a dirty tree, so neither can invent a merge commit or a conflict underneath a running agent; `push` pushes `HEAD`, never a branch name from the request. Network actions carry a 60s timeout |
 | `lib/proof.js`            | (C) Proof gallery: lists/serves/deletes QC screenshots grouped by feature slug (Task B's `lane_features`) and phase, under `<lane.cwd>/.playwright-mcp/proof/<slug>/<group>/`. Every path is resolved, realpath'd, and containment-checked before touching `fs` — the entire security surface. `ensureProofLink` ports Shipyard's `ensure_proof_link` (converge a stray clone-root `proof/` onto the canonical dir); never auto-invoked, exposed only as `agenthub lanes proof-link` |
 | `lib/named-lock.js`       | (D) Cross-lane named locks — the OTHER axis from `lib/lane-lock.js`'s per-lane, in-process serialization, deliberately a separate module. `mkdir` is the atomicity primitive (EEXIST decides "already held" in one syscall, never check-then-create). `LOCK_MAX_HOLD` (default 2700s) breaks a stale holder on the next acquire, floored at 300s so the floor — not the configurable default — is the actual safety property: nothing can force-break a live holder by setting the env var low. Single-shot only; the CLI's `agenthub lock acquire` owns the polling loop, keeping the server side non-orchestrating like every other lane primitive |
 
@@ -485,7 +487,7 @@ graph TD
 ### Splash & loading UX
 
 - **`SplashScreen.tsx`** — rendered by `App.tsx` as a fixed full-screen overlay alongside the router. Shows once per browser session (`sessionStorage` gate, read synchronously so a repeat mount never flashes). Time-aware greeting + localized tagline/subtexts (`splash` i18n namespace, en/zh/vi/ko) + an animated node-graph brand mark on a dark backdrop (radial glow, drifting constellation, grain). The backdrop is **opaque from the first paint** (no entrance fade on the root) so the app rendered behind it never flashes through; only the inner content cascades in. Holds ~2.5 s, then fades out and unmounts; click-to-skip; honors `prefers-reduced-motion`. CSS-only keyframes, no added dependencies.
-- **Colour tokens (`client/src/index.css`, `tailwind.config.js`)** — one CSS-variable set per mode, plus named-theme override blocks keyed by `data-theme` on `<html>` (Darcula, Apple Dark, Apple Light, IntelliJ Light, Canvas — picked in Settings → Appearance, `components/settings/AppearanceSettings.tsx`, state in `hooks/useTheme.ts`), consumed as `bg-surface-N` / `text-fg-*` / `border-border*` / `text-status-*` / `text-syntax-*`. The surface ramp encodes ELEVATION and rises in lightness with its index in BOTH themes: light mode's page is `surface-0` `#e8e5da` and a `.card` is the brighter `surface-3` `#f5f3ec` (Claude's warm ivory family rather than Radix slate — a cool near-white page reads as glare at any lightness, while dark mode stays slate + blue), so hovers lift instead of dimming. (Light mode previously used Radix slate in its native direction — index up meant darker — which put a near-white page under grey, recessed-looking cards: the "glaring and muddy at once" report.) Light `--accent` is `#924224` — Claude's terracotta three steps down, since the brand `#cc785c` is 3.1:1 on ivory — not dark's blue; `--accent` is a TEXT colour (dark Default `#70b8ff`), so white text sits on `--accent-solid` (`bg-accent-solid`, `.btn-primary`, Switch, Checkbox — dark Default `#0076d1`, light = `--accent`), never on `--accent`; `--fg-muted` is held at ≥4.5:1 because it carries timestamps and counts; `--shadow-card`, not the deliberately quiet `--border`, carries "raised" in light mode. Syntax colouring is tokenised too (`--syn-*`), dark keeping its 300-level pastels and light taking the same hues four steps darker. A hardcoded near-black panel, a `hover:text-white`, or `filter: invert(1)` on a form glyph is by definition a light-mode bug — token it, or scope it under `.dark`. Status and accent **fills** are pre-mixed rather than translucent: `tint()` in `tailwind.config.js` compiles `bg-status-success/10` and `border-status-danger/40` to `color-mix(…, rgb(var(--tint-base)))`, because an alpha tint composites with what is behind it and made one chip render as five different colours over the five surface steps. It is deliberately scoped to `backgroundColor`/`borderColor` — `text-*/NN` and `ring-*/NN` must stay translucent, and a translucent `surface` is what every scrim is made of.
+- **Colour tokens (`client/src/index.css`, `tailwind.config.js`)** — one CSS-variable set per mode, plus named-theme override blocks keyed by `data-theme` on `<html>` (Darcula, Apple Dark, Apple Light, Canvas — picked in Settings → Appearance, `components/settings/AppearanceSettings.tsx`, state in `hooks/useTheme.ts`), consumed as `bg-surface-N` / `text-fg-*` / `border-border*` / `text-status-*` / `text-syntax-*`. The surface ramp encodes ELEVATION and rises in lightness with its index in BOTH themes: light mode's page is `surface-0` `#eceef2` and a `.card` is the brighter `surface-3` `#fdfdfe` (the light Default is IntelliJ Light's palette), so hovers lift instead of dimming. (Light mode previously used Radix slate in its native direction — index up meant darker — which put a near-white page under grey, recessed-looking cards: the "glaring and muddy at once" report.) Light `--accent` is IntelliJ's `#285ac0`, darker than dark's blue; `--accent` is a TEXT colour (dark Default `#70b8ff`), so white text sits on `--accent-solid` (`bg-accent-solid`, `.btn-primary`, Switch, Checkbox — dark Default `#0076d1`, light = `--accent`), never on `--accent`; `--fg-muted` is held at ≥4.5:1 because it carries timestamps and counts; `--shadow-card`, not the deliberately quiet `--border`, carries "raised" in light mode. Syntax colouring is tokenised too (`--syn-*`), dark keeping its 300-level pastels and light taking IntelliJ Light's editor scheme. A hardcoded near-black panel, a `hover:text-white`, or `filter: invert(1)` on a form glyph is by definition a light-mode bug — token it, or scope it under `.dark`. Status and accent **fills** are pre-mixed rather than translucent: `tint()` in `tailwind.config.js` compiles `bg-status-success/10` and `border-status-danger/40` to `color-mix(…, rgb(var(--tint-base)))`, because an alpha tint composites with what is behind it and made one chip render as five different colours over the five surface steps. It is deliberately scoped to `backgroundColor`/`borderColor` — `text-*/NN` and `ring-*/NN` must stay translucent, and a translucent `surface` is what every scrim is made of.
 - **`Tooltip.tsx` (`GlobalTooltip`)** — mounted once by `App.tsx` beside the router. Every control in the app keeps writing the native `title="…"`; this listener upgrades it in place — on a 350 ms hover rest or immediately on keyboard focus it parks the attribute in `data-tip`, renders an anchored bubble (portal, arrow, flip above/below, viewport clamp, theme tokens so light mode is legible), and restores the attribute when it closes on pointer-out / pointer-down / scroll / resize / `Escape`. No wrapper at the call site, nothing to remember for the next `title=`, and the native tooltip plus the control's accessible name survive with JS off. `data-tip-off` opts an element out; `Tip.tsx` (cursor-following, for expanding a truncated number mid-sentence) draws the same `TOOLTIP_SURFACE`.
 - **Loading skeletons** — the shared `Skeleton` primitive (`components/Skeleton.tsx`) uses Tailwind `animate-pulse`. `Analytics.tsx` now renders a pulsing `AnalyticsChartsSkeleton` for the whole chart region while `data` is null (previously it fell back to empty/zero charts).
 - **`Workflows.tsx` `Section`** — the right-aligned section subtitle is clamped to a single line (`truncate` + `max-w` + hover `title`) so a long translation never wraps and unbalances the header; the full text stays in the section's `i` popover.
@@ -850,7 +852,7 @@ erDiagram
     alert_rules {
         TEXT id PK "UUID"
         TEXT name "User-facing rule name"
-        TEXT rule_type "event_pattern|inactivity|status_duration|token_threshold"
+        TEXT rule_type "event_pattern|inactivity|status_duration|token_threshold|cost_threshold|budget (no CHECK; validated in lib/alerts.js)"
         TEXT config "Type-specific JSON config"
         INTEGER enabled "1|0"
         INTEGER cooldown_seconds "Per-scope dedup window, default 300"
@@ -909,10 +911,10 @@ erDiagram
 | `idx_agents_status`    | agents   | `status`          | Kanban board column queries    |
 | `idx_events_session_created` | events | `session_id, created_at` | A session's newest event / time order (watchdog every 15 s, every lane payload) |
 | `idx_events_tool` | events | `tool_name` | Per-tool counts (analytics, workflows) and the events filter's tool list without a scan of every event row |
-| `idx_events_session` | events | `session_id, id` | A session's events in insert order: every hook's duplicate guard reads the latest one. Not a prefix of `idx_events_session_type` (that one is not id-ordered); dropping it once made every hook sort its whole session |
+| `idx_events_session` | events | `session_id, id` | A session's events in insert order: every hook's duplicate guard reads the latest one. Not a prefix of `idx_events_session_type_tool` (that one is not id-ordered); dropping it once made every hook sort its whole session |
 | `idx_events_type`      | events   | `event_type`      | Filter events by type          |
 | `idx_events_created`   | events   | `created_at DESC` | Activity feed ordering         |
-| `idx_events_session_type` | events | `session_id, event_type` | Per-session event-type filters |
+| `idx_events_session_type_tool` | events | `session_id, event_type, tool_name, created_at` | Per-session event-type filters, and a covering read for session stats (per-tool and per-type counts), the hook's TurnDuration/APIError dedupe and the import's newest-per-type resume point (1.2 s → 20 ms on a 29K-event session). Replaces `idx_events_session_type` (dropped at startup), so a hook writes no more index entries than before |
 | `idx_events_agent_type` | events  | `agent_id, event_type` | `importSubagentFromJsonl` reads the agent's existing `tool_use_id`s once through it (it used to run a `data LIKE` per tool event) |
 | `idx_sessions_status`  | sessions | `status`          | Status filter on Sessions page and Kanban Sessions view |
 | `idx_sessions_started` | sessions | `started_at DESC` | Default sort order             |
@@ -964,6 +966,11 @@ All messages are JSON with this envelope:
 }
 ```
 
+Frames a hook produces are sent only after its transaction committed and its
+pane binding (`bindRunSession`) ran — in order, in the same tick — so no frame
+describes a rolled-back row, and a server-mode member's first frames of a new
+session reach them. `new_event` carries the event's row `id` (additive).
+
 The `remote_source.status` message (emitted by the **Remote Data Sources**
 sync poller and the `/api/remote-sources` routes) carries
 `{ id, status, error?, last_sync_at? }`, where `status` is one of
@@ -1731,6 +1738,29 @@ is ever inferred.
 
 ---
 
+## Cursor Sessions
+
+`server/lib/cursor-usage.js` (`startCursorUsagePoll`, every
+`DASHBOARD_CURSOR_POLL_MS`, default 15000, `0` disables) reads the agent
+transcripts Cursor writes — the CLI (`cursor-agent`) and the editor's agent both —
+at `~/.cursor/projects/<project slug>/agent-transcripts/<id>/<id>.jsonl`
+(`AGENTHUB_CURSOR_DIR` overrides `~/.cursor`). Each becomes a `sessions` row with
+`tool = 'cursor'`: id = file name, name = the first `<user_query>` line (60
+chars), start = the file's birth time (mtime where there is none), `active`
+while it was written in the last two minutes, else `completed` at its last
+write. The cwd is the project slug walked back onto the filesystem (every
+non-alphanumeric character is a `-` in the slug, so only a path that still
+exists resolves); otherwise it stays NULL. `cursor_transcripts` holds the mtime
+read, so a session the user deleted stays deleted until Cursor writes to it again.
+
+**No tokens, no model, no cost.** A transcript line is `{role, message:{content}}`
+or `{type: "turn_ended"}` — no usage, no model id, no timestamps — so a Cursor
+session has no `token_usage` rows. The editor's `state.vscdb` keeps a
+`tokenCount` per chat bubble and a display model name (`GPT`, `default`, a BYOK
+name); AgentHub does not read it. No Cursor hooks are installed.
+
+---
+
 ## Agent Extension Layer
 
 The repository includes a triple extension strategy:
@@ -2194,7 +2224,7 @@ sequenceDiagram
 | --- | --- |
 | **`server/lib/update-check.js`** | `getUpdatesStatus(root?, { skipFetch?, latestRelease? })` + `applyUpdate(root?)`. Runs every git call via `execFile` (no shell, 10s–120s timeouts) and reads the newest release over `fetch` with an `AbortSignal.timeout` — `fetchLatestRelease` NEVER throws, resolving to `{ok:false, reason}` (`no_remote`, `remote_not_http`, `no_releases`, `unreachable`, `bad_payload`, `http_<status>`) so a status poll degrades instead of erroring. `releaseApiUrl` derives the endpoint from a repository URL (https, scp-style and `ssh://` forms) and returns null for anything not owner/repo shaped, which is what keeps local-path remotes off the network entirely. `fetchLatestRelease` finds that URL via the `origin` remote; `fetchReleaseFromUrl` takes one directly, which is how the **git-free plugin path** works: `pluginMarketplaceUrl(mkt, plugin)` reads `known_marketplaces.json` → the marketplace's `.claude-plugin/marketplace.json` → the entry's `source.url`, returning null (never a guessed host) for a `github` `owner/repo` shorthand and never throwing. **Order matters:** `detectPluginInstall` runs FIRST in `getUpdatesStatus`, ahead of the `.git` probe — a plugin cache unpacked from an archive has no `.git`, and probing first is the 1.5.1 bug that made `update_available` permanently false. `compareVersions` orders numeric triples and strips a leading `v`, since this repo carries both `v1.5.0` and `1.4.6`. `isShallowClone` gates every commit-distance calculation; `detectPluginInstall` reads the marketplace and plugin name out of the cache path. **Branch- and fork-aware** as before: resolves `<remote>/master`/`/main`/`/HEAD`, reads the current branch and its tracked upstream, and shapes `manual_command` per situation — the `claude plugin ...` commands for `plugin_managed`; `git fetch <remote> --tags && git merge --ff-only <tag>` for `release_available`; `git pull --ff-only` when the branch tracks the canonical ref; `git fetch <remote> && git merge --ff-only <ref>` for forks; `git fetch <remote>` only on a feature branch or detached HEAD. Non-git installs, missing remotes, fetch failures, and unresolvable upstream refs are returned as soft payloads — never throws. |
 | **`server/update-scheduler.js`** | Ticks the lib every `DASHBOARD_UPDATE_CHECK_INTERVAL_MS` (default 300 000, floor 60 000). First tick is scheduled 8s after server start with `.unref()` so it doesn't block shutdown. Broadcasts only when the fingerprint `{update_available, remote_sha, commits_behind, fetch_error, manual_command}` changes — `manual_command` is included so situation transitions (e.g. user switches branches, or adds an `upstream` remote) trigger a re-broadcast even when the SHA and commit count are unchanged. Emits a framed message to stdout on "up-to-date → behind" transitions, and only suggests "restart the dashboard" when the printed command actually rewrites the working tree. `DASHBOARD_UPDATE_CHECK=0\|false\|off` disables the scheduler entirely. |
-| **`server/routes/updates.js`** | Three endpoints: `GET /status` (read-only check), `POST /check` (check + broadcast), `POST /apply`. `/apply` has **two modes**, chosen by how this copy was installed, never by the request body: **checkout** — fast-forward onto the release tag, `npm run setup`, `npm run build` in production, then `scheduleRestart()`; **plugin** — `applyUpdate`'s `plugin_managed` refusal is caught and `schedulePluginUpdate()` runs instead, answering `200 {applied:true, mode:"plugin"}`. The plugin branch fires only when there is genuinely something to pull (`update_available` plus a marketplace and plugin name parsed from the cache path) — a `plugin_managed` refusal with nothing newer published stays a 409 rather than spawning a chain that would stop the server for nothing. Otherwise 409 `UPDATE_NOT_APPLICABLE` with `reason` `"up_to_date"`, `"not_fast_forwardable"`, or `"plugin_managed"`. Both modes write the response BEFORE anything stops the process. Mounted under `/api/*`, so all three ride the default loopback bind as their trust boundary and are gated by `DASHBOARD_TOKEN` when one is set. |
+| **`server/routes/updates.js`** | Three endpoints: `GET /status` (read-only check), `POST /check` (check + broadcast), `POST /apply`. `/apply` has **two modes**, chosen by how this copy was installed, never by the request body: **checkout** — fast-forward onto the release tag, `npm run setup`, `npm run build` in production (both through the bootstrap's `npmCommand` with `NODE_ENV` dropped — `npmInvocation` in `server/lib/update-check.js` — since the server's `NODE_ENV=production` makes npm omit the client's devDependency build toolchain, and a bare `npm.cmd` is EINVAL under `execFile` on Windows), then `scheduleRestart()`; **plugin** — `applyUpdate`'s `plugin_managed` refusal is caught and `schedulePluginUpdate()` runs instead, answering `200 {applied:true, mode:"plugin"}`. The plugin branch fires only when there is genuinely something to pull (`update_available` plus a marketplace and plugin name parsed from the cache path) — a `plugin_managed` refusal with nothing newer published stays a 409 rather than spawning a chain that would stop the server for nothing. Otherwise 409 `UPDATE_NOT_APPLICABLE` with `reason` `"up_to_date"`, `"not_fast_forwardable"`, or `"plugin_managed"`. Both modes write the response BEFORE anything stops the process. Mounted under `/api/*`, so all three ride the default loopback bind as their trust boundary and are gated by `DASHBOARD_TOKEN` when one is set. |
 | **`server/lib/plugin-update.js`** + **`scripts/plugin-update-helper.js`** | The plugin-cache update chain. The lib only spawns the helper detached (cwd = the runtime dir, **not** the plugin root, which is about to be superseded) and clears any previous verdict first so a stale success can't be read back as this run's result. All work is in the helper because its last step SIGTERMs the server that asked for the update — the same split as `self-restart.js`, one step further. The helper re-validates the marketplace and plugin names against `/^[A-Za-z0-9][\w.-]*$/` (they reach an argv across a process boundary), resolves `claude` on PATH or at `~/.local/bin/claude` (a hook-spawned server does not inherit the login shell's PATH), picks the newest cache directory that isn't the old root and does contain `scripts/plugin-bootstrap.js`, and records **every** outcome — including an unexpected throw — to `plugin-update.json` under `~/.claude/agenthub/runtime/`, outside the cache so it survives the swap. Steps: `validate`, `resolve_claude`, `marketplace_update`, `plugin_update`, `already_current` (`ok:true`; nothing was pulled and the old server was left running), `bootstrap`, `done`. `readLastPluginUpdate()` surfaces it as `last_plugin_update` on the status payload — without it a failed chain is indistinguishable from a slow one. |
 | **`UpdateNotifier.tsx`** | Modal. Hydrates from `api.updates.status()` on mount and mirrors the payload back into the local `eventBus` so the Sidebar can listen without a second git fetch. Subscribes to `update_status` WS frames for ongoing sync. Keeps the dismissal key in `localStorage` (`agent-monitor-update-dismissed-sha`) and in React state — the **release tag** when one was read, else the upstream SHA, so a newer release re-opens the prompt while a dismissed one stays dismissed; a window event `dashboard:reset-update-dismissal` from the Sidebar clears both. ESC / backdrop click dismisses. |
 | **`Sidebar.tsx`** | The update state and its **Check for updates** button live in the connection details modal the sidebar owns (opened from the status bar; the sidebar has no footer); the status bar shows a green dot beside the version while a release is out. Subscribes to `update_status` (no own fetch). On click: clears dismissed SHA in localStorage, dispatches `dashboard:reset-update-dismissal`, then calls `api.updates.check()`. Visual state: emerald badge when `update_available`, amber when `fetch_error`, neutral otherwise. Label has four resting states, not two — `"<tag> available"`, `"Dev build · N ahead"` (when `dev_build`), `"Up to date"`, or `"Check for updates"` before the first result. |
@@ -2214,6 +2244,7 @@ interface UpdateStatusPayload {
   situation?:                          // categorical hint for the UI
     | "plugin_managed"                 // ~/.claude/plugins/cache — /apply delegates
     | "release_available"              // fast-forward onto the release tag
+    | "diverged_from_release"          // HEAD has commits the release lacks — fetch only, no apply
     | "tracking_canonical"
     | "fork_or_diverged_tracking"
     | "feature_branch"
@@ -2271,14 +2302,15 @@ The same shape is used by `GET /status`, `POST /check`, and the `update_status`
 | Ahead of the newest release | `{update_available:false, dev_build:true, commits_ahead_of_release:N}` | Sidebar reads `Dev build · N ahead`; modal suppressed (a dev build is not an available update). |
 | Shallow clone (incl. the plugin cache) | `{shallow_clone:true, commits_behind_release:null, commits_ahead_of_release:null, dev_build:false}` | No commit badge is rendered at all — the numbers would be graft artefacts. Version compare still decides `update_available`. |
 | Newer release, ordinary checkout | `{update_available:true, situation:"release_available", latest_release:"vX.Y.Z", manual_command:"...git fetch origin --tags && git merge --ff-only vX.Y.Z..."}` | Modal opens titled with the release version, links its notes, and shows **Update now**. |
-| Newer release, plugin-cache install | `{update_available:true, situation:"plugin_managed", install_kind:"plugin", plugin_marketplace:"sg", plugin_name:"agenthub", manual_command:"claude plugin marketplace update sg && ..."}` | Modal opens WITH **Update now**; `POST /apply` answers `200 {applied:true, mode:"plugin"}` and the detached chain pulls the new version and re-bootstraps. The modal notes that an already-open Claude Code session still needs `/reload-plugins` for new skills/commands. |
-| Plugin chain ran but nothing was published | `{last_plugin_update:{ok:true, step:"already_current"}}` | The old server keeps running, untouched; no restart, no error banner. |
+| Newer release, plugin-cache install | `{update_available:true, situation:"plugin_managed", install_kind:"plugin", plugin_marketplace:"sg", plugin_name:"agenthub", manual_command:"claude plugin marketplace update sg && ..."}` | Modal opens WITH **Update now**; `POST /apply` answers `200 {applied:true, mode:"plugin"}` and the detached chain pulls the new version and re-bootstraps. The modal notes that an already-open Claude Code session still needs `/reload-plugins` for new skills/commands. It then polls `status` and reloads once the old server went down and answered again, or as soon as a different `local_version` answers; a verdict of this chain (`finished_at` after the click) that is `ok:false` or `already_current` ends the wait and shows it, since the old server then never goes down. Independently, every tab reloads itself onto the new UI build when its WebSocket reconnects to a server whose `/api/health` `version` is not the bundle's (`client/src/lib/newBuildReload.ts`, once per version). |
+| Plugin chain ran but nothing was published | `{last_plugin_update:{ok:true, step:"already_current"}}` | The old server keeps running, untouched; no restart, no error banner — a tab waiting on **Update now** stops waiting and says nothing new was pulled. |
 | Plugin chain mid-handover | `{last_plugin_update:{ok:true, step:"bootstrap", note:"the new plugin version is installed; the server is being handed over"}}` | Written BEFORE the handover on purpose: that step retires the process tree the helper hangs off, and a helper killed there would otherwise leave `last_plugin_update: null` for an update that succeeded. Overwritten by `done` when the helper survives. |
 | Plugin chain failed (no `claude` on PATH, `npm ci` broke, bootstrap died) | `{last_plugin_update:{ok:false, step:"resolve_claude"\|"plugin_update"\|"bootstrap", error:"..."}}` | Danger banner in the modal naming the failed step. A `bootstrap` failure means the old server was already stopped, so the verdict says to run `/agenthub-update` to recover — and it is read back by whichever server comes up next, because it lives outside the cache. |
 | Plugin `/apply` with nothing newer published | 409 `{reason:"plugin_managed", release_check:"ok"}` | No chain is spawned. Message names the newest release and points at `/agenthub-update` to force a refresh. |
 | Plugin `/apply` after a failed release check | 409 `{reason:"plugin_managed", release_check:"unreachable"\|"no_local_version"\|...}` | No chain is spawned, and the message says the check did not succeed rather than claiming nothing newer exists — an unknown reported as a negative is how a broken check looks identical to an up-to-date install. |
 | Healthy, behind, on canonical branch | `{update_available:true, situation:"tracking_canonical", manual_command:"...git pull --ff-only..."}` | Modal opens with `git pull` flow + restart hint. |
 | Healthy, behind, fork (origin = fork, upstream = canonical) | `{update_available:true, situation:"fork_or_diverged_tracking", manual_command:"...git fetch upstream && git merge --ff-only upstream/master..."}` | Modal opens with merge flow + restart hint + `situation_note` explaining the divergence. |
+| Newer release, but HEAD holds commits the release lacks (e.g. local wip the release squashed) | `{update_available:true, situation:"diverged_from_release", manual_command:"...git fetch <remote> --tags"}` | Modal opens with no **Update now**; `situation_note` says how many commits diverge and offers `git reset --keep <tag>` (when they are already in the release) or merge/rebase. `/apply` answers `not_fast_forwardable` instead of a raw `merge --ff-only` failure. |
 | Healthy, behind, on a feature branch | `{update_available:true, situation:"feature_branch", manual_command:"...git fetch <remote>"}` | Modal opens; `situation_note` explains the user is off the canonical branch; restart hint suppressed because the working tree isn't being changed. |
 
 ### Why Self-Apply Stays Narrow
@@ -2291,7 +2323,7 @@ The same shape is used by `GET /status`, `POST /check`, and the `update_status`
 - **Branch coverage.** A feature branch or detached HEAD would need branch-aware integration (rebase vs merge vs switch) and merge-conflict handling. That belongs in the user's shell, not in a background daemon — which is why those situations get a printed `git fetch` and no button.
 - **Ownership.** A plugin-cache install is not ours to rewrite by hand — its directory names are content hashes Claude Code manages. So that case does not fast-forward anything; it calls `claude plugin update` and then re-runs `plugin-bootstrap.js` from the directory that tool produced. The residual limit is only `/reload-plugins`, which is REPL-scoped: an interactive session keeps its old skills/commands until the user reloads, even though the dashboard server has already moved.
 
-What `--ff-only` buys is the absence of the first three problems inside the supported cases: the move is either a clean fast-forward or it aborts, `npm run setup`/`build` failures reject the request before any restart is scheduled, and the restart itself goes through `self-restart.js` + the detached `scripts/restart-helper.js` rather than an in-process guess at the supervisor.
+What `--ff-only` buys is the absence of the first three problems inside the supported cases: the move is either a clean fast-forward or it aborts, `npm run setup`/`build` failures reject the request before any restart is scheduled, and the restart itself goes through `self-restart.js`: a server our own service unit runs (its cgroup ends in `/agenthub.service`, or it is our launchd job) is restarted BY that manager (`systemctl restart --no-block`, via `sudo -n` for the server-mode system unit; launchd's KeepAlive after an exit), anything else by the detached `scripts/restart-helper.js`. A detached replacement under a `Restart=always` unit held the port while the unit restarted every 3 s, each start exiting "already running" (v2.7.2).
 
 ---
 

INSTALL.md

@@ -18,7 +18,7 @@ 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).
+uninstall cleanup (`agenthub uninstall`), is in [`docs/PLUGINS.md`](docs/PLUGINS.md).
 
 Follow the steps below instead when you want a checkout — to develop the
 dashboard, run it from source, or stay on Node 20.
@@ -117,9 +117,10 @@ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # where the plugin put
   `node:sqlite`); a checkout still runs on Node 20. 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 by itself (LaunchAgent).** The plugin bootstrap installs
-  `~/Library/LaunchAgents/io.smartgift.agenthub.plist` (a checkout: `agenthub
-  service install`), so the dashboard comes back after every login with no
+- **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
@@ -322,7 +323,7 @@ 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).
 
 ---

README.en.md

@@ -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.

README.md

@@ -1,336 +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; **workspaces** track
-parallel agent work, one working directory each; and the `agenthub` CLI drives real terminal
-sessions, workspace 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.
 
-Internal build — all rights reserved.
+| 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) |
 
-*(Tiếng Việt: [README.vi.md](README.vi.md))*
+<a id="requirements"></a>
 
-## Main features
+## Yêu cầu
 
-**Observe**
+- **Node.js ≥ 22.5**
+- **git**
+- **tmux**
 
-- **Sessions, agents, events.** Everything Claude Code emits, recorded and
-  searchable: tool calls, token usage, cost, subagent trees, transcripts.
-- **Analytics and cost.** Per-model token totals and estimated cost, with
-  editable pricing rules; top tools, agent types, and workflow patterns.
-- **Activity feed and alerts.** A live event stream, alert rules, and webhook
-  targets that fire on them.
-- **History import.** Every session under `~/.claude/projects/` is imported on
-  startup; archives from another machine come in through Settings → Import
-  History (idempotent, never double-counts tokens).
-- **Remote sources.** Pull session history from other machines over SSH
-  (`agenthub remote-sources`).
+Cài:
 
-**Drive**
+- Ubuntu: `sudo apt install git tmux` (Node.js ≥ 22.5 tải ở <https://nodejs.org>)
+- macOS: `brew install node git tmux`
 
-- **Workspaces.** One workspace per working directory, surviving session restarts. Once you
-  install a pipeline template (none ships), a workspace moves through its stages and
-  the dashboard shows where it is.
-- **Stage detection.** With a template installed, 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 workspace's directory — the exact TUI
-  you'd see locally, fully interactive, resumable, and attachable from a real
-  terminal too via `agenthub workspace shell`. Which CLI it starts is the workspace's own
-  setting. **This is the part that needs `tmux` installed** — see
-  [Prerequisites](#prerequisites).
-- **Git, from the dashboard.** Each workspace card shows its branch, `↑ahead ↓behind`
-  and its uncommitted files, with buttons for the ordinary moves: fetch, pull
-  (always `--ff-only`), push, commit-all, and switching branch on a clean tree.
-  Beside the workspace sits a collapsible **Changes** panel — an overview of the
-  changed files, a full review of every diff, or one file at a time, comparing
-  either uncommitted work or the whole branch against its base. There is no
-  merge/rebase/reset button by design: recovery from those needs a terminal.
-- **Per-workspace app stacks.** A repo that declares `.agenthub/profile/` gets its own
-  slot, ports and services per workspace (`agenthub workspace up|down|logs`).
+<a id="install-claude-code"></a>
 
-**Configure**
+## Cách 1 — Cài qua Claude Code (khuyên dùng)
 
-- **Workspaces like Claude Desktop projects.** The sidebar lists every
-  workspace with its sessions under it (a live one opens its tmux pane, any
-  other its conversation with a prompt box — sending a message resumes it,
-  opening never does; **Analyst** in the right panel opens its analysis). A workspace opens on its home: a
-  prompt box that starts a new session, Recents, and the workspace's own
-  Instructions, Memory, Context files and extra Folders, which Claude and Codex
-  sessions start with.
-- **Settings as one page per section** (`/settings/<section>`): a left nav
-  grouped General (General / Data / About / Appearance / Pet / Notifications) /
-  Agents / Routing / Cost / Git, a search box (Ctrl+F) over every section whose
-  results deep-link a row's sub-tab and anchor, a page per installed AI tool, per-vendor model pricing, and which
-  untracked worktrees a workspace's Add folder suggests.
-- **Claude Code + Codex configuration explorer.** Settings hosts one page per
-  tool: every plugin, skill, subagent, slash command, MCP server, hook, settings
-  file, memory file, marketplace, keybinding and statusline Claude Code knows
-  about — read for all of them, edit/create/delete for the text-file surfaces
-  (skills, agents, commands, output styles, `CLAUDE.md`). Plugins, MCP, hooks and
-  `settings.json` stay read-only: they race with the live CLI.
-- **Updates.** Release-based update detection with an in-UI **Update all**
-  (marketplaces → every plugin → AgentHub last → one session reload).
-- **Appearance.** Settings → Appearance picks Dark / Light / System (follows the
-  OS live) and a theme per mode — dark: Default, Darcula, Apple Dark, Orca Dark;
-  light: Default, Apple Light, IntelliJ Light, Canvas, Orca Light. Each mode
-  remembers its own theme, so the sidebar's quick toggle swaps between the two.
-  Per-browser only.
-- **Notification sounds.** Settings → Notifications picks a sound (None, Chime,
-  Pop, Alert — off by default) played with every notification shown, and each
-  notification type can pick its own.
-- **A CLI for all of it** (`agenthub`, plus `agenthub repl`), a PWA install, and
-  a UI in English, Vietnamese, Chinese and Korean.
-
-## Prerequisites
-
-| Need | Version | Required for |
-|---|---|---|
-| **Node.js** | >= 20 (>= 22.5 for a plugin install) | Everything. Both suites are verified green on **24** and **26** |
-| **npm** | 9+ | Ships with Node |
-| **git** | any | Cloning, and every workspace operation (worktrees, branch/status reads) |
-| **tmux** | 3.x | The browser run console, `agenthub workspace shell`, typing `/reload-plugins` into a live pane |
-| **Claude Code** | 2.x | Hook ingestion — the whole monitoring side |
-| **Codex CLI** | any | Optional — only for `codex` workspaces |
-| **GitHub CLI (`gh`)** | any | Optional — only for `agenthub workspace ci status` |
-| **systemd (user)** | — | Optional — only for `agenthub service install` (Linux auto-start on boot) |
-
-Node **25** is the one version to avoid: it breaks 6 server tests through a
-better-sqlite3 ABI mismatch and 20 client tests through a global `localStorage`
-change. Both were gone again by 26 (1712 server + 488 client tests green on
-v26.8.1).
-
-### Installing tmux
-
-The dashboard shells out to the `tmux` binary; there is no bundled fallback, so
-**Start Run** and `agenthub workspace shell` fail without it. Everything else
-(sessions, analytics, workspaces, stage detection, the CLI) works fine.
-
-```bash
-sudo apt install tmux        # Debian / Ubuntu
-sudo dnf install tmux        # Fedora / RHEL
-brew install tmux            # macOS
-sudo pacman -S tmux          # Arch
-```
-
-Windows has no native tmux — run AgentHub under WSL2 and install it there.
-
-macOS (code-audited, untested on a Mac): `brew install node git tmux` (Node
->= 22.5 for the plugin), add `~/.local/bin` to `PATH` in `~/.zshrc`. There is
-no systemd, so the dashboard runs until logout/reboot and comes back at the
-next Claude Code session, or by hand with `agenthub start`. Details and a
-checklist to verify it: [INSTALL.md § macOS](INSTALL.md#macos).
-
-Verify, both from your shell and from the server's point of view:
-
-```bash
-tmux -V                                      # e.g. tmux 3.4
-curl -s localhost:4820/api/run/tmux          # {"available":true}
-```
-
-A workspace's run lives in a tmux session named `agenthub-lane-<id>`, so the browser
-terminal and a local `tmux attach -t agenthub-lane-<id>` (or `agenthub workspace
-shell`) are two clients on the same pane — they stay in sync, and killing the
-dashboard never kills the run.
-
-## Install as a Claude Code plugin
-
-Two commands on a machine that has nothing but Claude Code, no clone and no
-`npm run setup`:
+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
 ```
 
-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 and client dependencies
-npm run build          # builds the client into client/dist
-npm start              # serves the built client and the API on :4820
+```
+/agenthub:agenthub-open
 ```
 
-Open <http://localhost:4820>.
+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.
 
-Development, with hot reload:
+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
-npm run dev            # server on :4820, Vite client on :5173
+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
 ```
 
-`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.
+Mở <http://localhost:4820> trên trình duyệt.
 
-### 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. `agenthub service install` sets up a
-systemd `--user` service (Linux) or a LaunchAgent (macOS) 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:
+`npm start` tắt khi đóng terminal. Muốn dashboard tự chạy mỗi lần bật máy:
 
 ```bash
-npm run build              # the service serves the built client, same as npm start
-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
+agenthub service install
 ```
 
-On Linux, `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`.
+> ⚠️ Chỉ chọn **một** trong hai cách. Cài cả hai thì mỗi sự kiện bị đếm hai lần.
 
-## The CLI
+<a id="more-docs"></a>
 
-`agenthub` is linked by `npm run setup`; otherwise call `node bin/agenthub.js`.
+## Tài liệu thêm
 
-```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 workspaces        # workspaces with stage and progress
-agenthub workspace pipeline    # this lane's pipeline template, or switch it
-agenthub workspace node <id>   # run ONE pipeline node's own command (no id: list them)
-agenthub stage <name>      # declare the current lane's stage
-agenthub tail              # live event feed
-```
+- 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)
 
-`agenthub --help` lists the rest.
-
-## Workspaces
-
-A workspace 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 may
-  reset that worktree, behind a three-check destroy guard and a counted preflight
-  the caller has to echo back. Removing a workspace — either kind — deletes only the
-  dashboard's record of it: the working tree, its branch and its database stay,
-  for you to delete yourself.
-
-```bash
-agenthub workspace add --cwd /path/to/repo --title "My feature"    # adopt
-agenthub workspace add --repo /path/to/repo --slug my-feature      # managed worktree
-```
-
-Every workspace also carries the CLI that drives it — `claude` (the default) or
-`codex` — picked in the Add-workspace modal and fixed for the life of the workspace. A
-Codex workspace's run panel offers Codex's own sandbox, approval and reasoning-effort
-choices, and resumes with `codex resume --last`. Codex sessions and token usage
-are read from Codex's own rollout journals: every Codex session (a workspace's or
-not) appears in Sessions with a **Codex** badge and is priced like any other,
-with OpenAI rates filled in automatically (Settings → Codex → Overview). For a
-live feed, install **Codex hooks** from the same tab: the next time Codex starts
-it asks you to trust them (**Trust all and continue**), and from then on each
-tool call lands in the session's timeline, a codex workspace turns running/idle as
-each turn starts and ends, and "Codex needs your permission" shows on the workspace
-card and as a notification while Codex waits for an approval. A Codex workspace also
-carries **no pipeline** — no stage, no pipeline map, nothing inferred or
-advanced; without hooks the dashboard mirrors its running/idle status from the
-rollout journals on disk (`$CODEX_HOME/sessions/**/rollout-*.jsonl`, polled
-every `DASHBOARD_CODEX_POLL_MS` ms, default 15000).
-
-An **Antigravity** workspace runs Antigravity's `agy` CLI. Its sessions and token
-usage are read from agy's own conversation files
-(`~/.gemini/antigravity-cli/conversations/<id>.db`, every
-`DASHBOARD_ANTIGRAVITY_POLL_MS` ms, default 15000): every agy CLI session
-appears in Sessions with an **Antigravity** badge, priced with Gemini rates that
-are filled in automatically (Settings → Antigravity). **Antigravity hooks**, in
-the same tab, add a live feed: each tool call in the session's timeline and a
-workspace that turns running/idle as a run starts and ends. agy asks for no trust,
-and it has no hook for a permission prompt, so an Antigravity workspace never shows
-"needs your permission". agy fires no hook when it exits, nor when a run ends
-on an API error or a permission refused in headless mode, so a session gone
-quiet is marked completed and its workspace set idle — after ten minutes of quiet
-for a session the hooks report on (a long tool call writes nothing, and after a
-Stop agy may still be waiting for you), after two minutes for one without
-hooks. Antigravity workspaces carry no pipeline either.
-
-**Pipelines are dormant.** AgentHub ships no pipeline template, so a workspace has no
-stages until you drop a template JSON into `DASHBOARD_PIPELINES_DIR` (see
-[`docs/LANES.md`](docs/LANES.md#custom-pipeline-templates)); until then
-`agenthub stage` answers `ENOPIPELINE` and the Workspace hides the pipeline map.
-Further development is planned.
-
-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 workspace can
-move backwards between work sessions. Detection never writes the declared stage,
-and an inferred node never renders as done.
-
-A workspace's pipeline template can be switched after creation — `agenthub workspace
-pipeline <template>` from the terminal, or the pipeline-template picker next to
-the workspace's title in the Workspace detail panel. Both re-resolve the workspace's
-current declared stage against the new template's nodes and warn if it no
-longer matches one.
-
-A workspace can also run **its own application stack**, isolated per workspace, when its
-repository declares a profile at `<repo>/.agenthub/profile/` — a `profile.env` of
-declarations plus shell hooks the dashboard calls. Each workspace gets a slot, and its
-ports and per-workspace directories derive from it:
-
-```bash
-agenthub workspace up          # boot the stack of the lane owning this directory
-agenthub workspace runtime     # slot, ports, service health
-agenthub workspace logs api    # tail a service log
-agenthub workspace down
-```
-
-Services are fully detached, so restarting the dashboard never stops a running
-workspace. This is resource namespacing on the host, not a container: workspaces 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, the git surface (`GET /api/lanes/:id/git`,
-`/git/changes`, `/git/log`, `/git/file`, `/git/ls`, `/git/tree`,
-`POST /:id/git/:action`), 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, workspace and worktree libraries |
-| `client/` | React 18 + Vite + Tailwind dashboard |
-| `bin/agenthub.js` | CLI |
-| `docs/` | Architecture, API, workspaces, 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) — workspaces, 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
+Internal build — all rights reserved.

bin/agenthub.js

@@ -40,7 +40,7 @@
 
 const path = require("node:path");
 const fs = require("node:fs");
-const { spawn } = require("node:child_process");
+const { spawn, spawnSync } = require("node:child_process");
 
 // Resolve the repo root relative to this script's REAL location so the CLI
 // works both from a checkout (./bin/agenthub.js) and through the global symlink
@@ -141,21 +141,10 @@ function termWidth() {
 /**
  * Resolve the dashboard base URL. Env override first (matches the hook
  * handler's contract), then the live-server discovery file, then the default
- * port. The discovery module is best-effort and never throws.
+ * port — shared with the MCP server and the statusline (`dashboard-url.js`).
  */
 function baseUrl() {
-  const envPort = process.env.CLAUDE_DASHBOARD_PORT || process.env.DASHBOARD_PORT;
-  if (envPort) return `http://127.0.0.1:${envPort}`;
-  try {
-    const { resolveDashboardPort } = require(
-      path.join(REPO_ROOT, "server", "lib", "server-info.js")
-    );
-    const port = resolveDashboardPort();
-    if (port) return `http://127.0.0.1:${port}`;
-  } catch {
-    /* discovery unavailable — fall through to the default */
-  }
-  return "http://127.0.0.1:4820";
+  return require(path.join(REPO_ROOT, "server", "lib", "dashboard-url.js")).dashboardUrl();
 }
 
 /** Thrown when the dashboard server does not answer — the dispatcher decides
@@ -171,7 +160,13 @@ async function api(method, pathname, body, options = {}) {
     const form = body instanceof FormData;
     res = await fetch(url, {
       method,
-      headers: body && !form ? { "Content-Type": "application/json" } : undefined,
+      headers: {
+        ...(body && !form ? { "Content-Type": "application/json" } : {}),
+        // Server mode: inside a dashboard pane, act as the workspace's owner.
+        ...(process.env.AGENTHUB_PANE_TOKEN
+          ? { "x-agenthub-pane-token": process.env.AGENTHUB_PANE_TOKEN }
+          : {}),
+      },
       body: body ? (form ? body : JSON.stringify(body)) : undefined,
       signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
     });
@@ -1037,6 +1032,8 @@ async function cmdRemoteSources(flags, positional) {
       ssh_port: flags.port != null ? Number(flags.port) : null,
       identity_file: flags.identity != null ? String(flags.identity) : null,
       remote_home: flags["remote-home"] != null ? String(flags["remote-home"]) : null,
+      sync_codex: !!flags.codex,
+      remote_codex_home: flags["codex-home"] != null ? String(flags["codex-home"]) : null,
       enabled: flags.disabled ? false : true,
     };
     const r = await post("/api/remote-sources", body);
@@ -1400,14 +1397,36 @@ async function cmdReinstallHooks() {
  * built client) and wait until /api/health answers. No-ops with a pointer to
  * the live URL when a server is already up. The child is fully detached with
  * its output appended to data/agenthub-server.log, so closing this terminal does
- * not stop the dashboard; stop it later with `kill <pid>` (the PID is
- * printed and registered in ~/.claude/.agenthub.json).
+ * not stop the dashboard; stop it later with `agenthub stop`.
  */
 async function cmdStart(flags) {
+  // A Quit (`agenthub stop`) held the plugin bootstrap off; starting ends it.
+  require(path.join(REPO_ROOT, "server", "lib", "quit.js")).clearQuit();
   if (await serverIsUp()) {
     console.log(`${c.green("●")} Dashboard already running at ${c.bold(baseUrl())}`);
     return;
   }
+  // A plugin install starts the way a Claude Code session does: its bootstrap
+  // knows the runtime dir, the UI bundle and the autostart unit.
+  if (/[\\/]\.claude[\\/]plugins[\\/]cache[\\/]/.test(REPO_ROOT)) {
+    spawnSync(
+      process.execPath,
+      [path.join(REPO_ROOT, "scripts", "plugin-bootstrap.js"), "--worker"],
+      {
+        stdio: "inherit",
+      }
+    );
+    const deadline = Date.now() + 30_000;
+    while (Date.now() < deadline) {
+      if (await serverIsUp()) {
+        console.log(`${c.green("●")} Dashboard ${c.bold("up")} at ${c.bold(baseUrl())}`);
+        return;
+      }
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    console.error(c.red("✖ Server did not become healthy within 30 s — run /agenthub-doctor"));
+    process.exit(1);
+  }
   const clientDist = path.join(REPO_ROOT, "client", "dist", "index.html");
   if (!fs.existsSync(clientDist)) {
     console.error(c.red("✖ client/dist is missing — the production server needs a built client."));
@@ -1450,7 +1469,7 @@ async function cmdStart(flags) {
       console.log(
         `${c.green("●")} Dashboard ${c.bold("up")} at ${c.bold(baseUrl())} ${c.dim(`(pid ${child.pid})`)}`
       );
-      console.log(c.dim(`  Stop it with: kill ${child.pid}`));
+      console.log(c.dim("  Stop it with: agenthub stop"));
       return;
     }
     tick++;
@@ -1466,6 +1485,79 @@ async function cmdStart(flags) {
   process.exit(1);
 }
 
+/**
+ * Quit AgentHub (issue #65): every lane pane is killed, the server stops, and
+ * the plugin bootstrap starts none until `agenthub start` — or a boot/login
+ * through an enabled autostart unit (`server/lib/quit.js`).
+ */
+async function cmdStop() {
+  if (!(await serverIsUp())) {
+    require(path.join(REPO_ROOT, "server", "lib", "quit.js")).markQuit();
+    console.log(
+      `${c.dim("○")} Dashboard is not running — it stays stopped until ${c.bold("agenthub start")}`
+    );
+    return;
+  }
+  const res = await post("/api/settings/quit", undefined, { allowError: true });
+  if (res?.status) {
+    // Server mode: a shell on the host carries no login, and Quit is an admin's.
+    if (res.data?.error?.code === "EAUTH" || res.data?.error?.code === "EADMIN") {
+      console.error(
+        `${c.red("✖ This dashboard runs in server mode: Quit needs an admin login.")}\n` +
+          "  Log in as an admin and use Settings → System → Quit AgentHub, or stop its service:\n" +
+          `    ${c.bold("sudo systemctl stop agenthub")}        ${c.dim("# system unit (one Linux user per account)")}\n` +
+          `    ${c.bold("systemctl --user stop agenthub")}     ${c.dim("# per-user unit")}`
+      );
+    } else {
+      const msg = res.data?.error?.message || `HTTP ${res.status}`;
+      console.error(c.red(`✖ POST /api/settings/quit → ${msg}`));
+    }
+    process.exit(1);
+  }
+  const { killed } = res;
+  const deadline = Date.now() + 15_000;
+  while ((await serverIsUp()) && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  if (await serverIsUp()) {
+    console.error(c.red(`✖ The dashboard at ${baseUrl()} is still answering after 15 s`));
+    process.exit(1);
+  }
+  console.log(
+    `${c.green("✔")} AgentHub stopped${killed ? ` — ${killed} terminal session(s) closed` : ""}. Start it again with: ${c.bold("agenthub start")}`
+  );
+}
+
+/**
+ * Uninstall AgentHub (scripts/uninstall.js): without `--yes` it only lists what
+ * would go. Needs no server — it is the thing being removed.
+ */
+function cmdUninstall(flags) {
+  const settingsEnv = require(path.join(REPO_ROOT, "server", "lib", "settings-env.js"));
+  settingsEnv.loadEnvFiles({ owned: [path.join(REPO_ROOT, ".env")] });
+  const uninstall = require(path.join(REPO_ROOT, "scripts", "uninstall.js"));
+  if (flags.yes !== true) {
+    const steps = uninstall.plan();
+    if (!steps.length) return console.log(`${c.dim("○")} Nothing of AgentHub's is left here`);
+    console.log(c.bold("agenthub uninstall --yes would:"));
+    for (const s of steps) {
+      console.log(`  ${c.red("✖")} ${s.label}`);
+      for (const i of s.items) console.log(c.dim(`      ${i}`));
+    }
+    console.log(
+      c.dim(
+        "  Kept: the AI tools' own conversations, workspace worktrees and branches, your repos."
+      )
+    );
+    console.error(c.red("Nothing was removed. Re-run with --yes: agenthub uninstall --yes"));
+    process.exitCode = 1;
+    return;
+  }
+  const r = uninstall.run({ onLine: (l) => console.log(l) });
+  console.log(c.dim(`Log: ${r.log}`));
+  if (!r.ok) process.exitCode = 1;
+}
+
 /**
  * Installs/removes a systemd `--user` service (Linux) or a LaunchAgent
  * (macOS) so the dashboard survives reboots without anything (Claude Code
@@ -2312,6 +2404,17 @@ async function cmdLockAcquire(args) {
       console.log(`${c.green("✔")} acquired lock "${name}" as ${holder}`);
       return;
     }
+    // Only 409 means "held by someone else"; any other answer (a refused
+    // name, a server error) will not change by waiting.
+    if (result.status !== 409) {
+      console.error(
+        c.red(
+          `✖ ${result.data?.error?.message || `could not acquire lock (HTTP ${result.status})`}`
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
     if (Date.now() - lastPrinted >= 60_000) {
       const waited = Math.floor((Date.now() - startedAt) / 1000);
       console.log(
@@ -2723,11 +2826,36 @@ const COMMAND_GROUPS = [
     [
       ["status", "", "Up/down indicator for the dashboard server"],
       ["start", "[--port N]", "Start the server in the background and wait for healthy"],
+      [
+        "stop",
+        "",
+        "Quit: close every workspace terminal and stop the server until `agenthub start`",
+      ],
+      [
+        "uninstall",
+        "[--yes]",
+        "Remove AgentHub from this machine, its database included (lists first without --yes)",
+      ],
       [
         "service",
         "install|uninstall|status [--port N]",
         "Auto-start on boot via systemd --user (Linux)",
       ],
+      [
+        "server",
+        "setup|off|status [--hostname name] [--admin name]",
+        "Server mode: logins for a shared dashboard (docs/SERVER-MODE.md)",
+      ],
+      [
+        "users",
+        "list|add|passwd|role|disable|enable|assign|audit [name]",
+        "Server mode's accounts (add: --role admin|analyst|developer)",
+      ],
+      [
+        "accounts",
+        "list|add|remove [name] [--tool codex]",
+        "Claude/Codex account pool: new sessions spread over these accounts",
+      ],
       ["repl", "", "Open the interactive shell (also: shell, i)"],
     ],
   ],
@@ -2797,7 +2925,7 @@ const COMMAND_GROUPS = [
       [
         "remote-sources add",
         "",
-        "--label X --host user@host [--port N --identity path --remote-home path]",
+        "--label X --host user@host [--port N --identity path --remote-home path --codex --codex-home path]",
       ],
       ["remote-sources test <id>", "", "Probe SSH connectivity to a source"],
       ["remote-sources sync [id]", "", "Pull history now (all sources if id omitted)"],
@@ -2917,6 +3045,27 @@ const COMMAND_GROUPS = [
       ],
     ],
   ],
+  [
+    "Integrations",
+    [
+      [
+        "mcp",
+        "",
+        "Run the read-only MCP server on stdio (claude mcp add agenthub -- agenthub mcp)",
+      ],
+      [
+        "tray",
+        "",
+        "Show AgentHub's icon in the OS status area now (the server keeps it up; Settings → System hides it)",
+      ],
+      ["statusline", "", "Render the Claude Code statusline from the JSON on stdin"],
+      [
+        "statusline install|uninstall",
+        "[--force]",
+        "Add/remove AgentHub's statusLine in ~/.claude/settings.json (--force: replace or remove another one)",
+      ],
+    ],
+  ],
   [
     "Administration",
     [
@@ -3661,11 +3810,506 @@ const COMMANDS = (() => {
 const SUBCOMMANDS = {
   alerts: ["ack", "ack-all"],
   service: ["install", "uninstall", "status"],
+  server: ["setup", "off", "status"],
+  users: ["list", "add", "passwd", "role", "disable", "enable", "assign", "audit"],
+  accounts: ["list", "add", "remove"],
   pricing: ["set", "delete", "reset"],
   webhooks: ["test"],
   import: ["rescan", "path"],
+  statusline: ["install", "uninstall"],
 };
 
+/** `agenthub statusline install|uninstall [--force]` — the user's settings.json. */
+function cmdStatusline(sub, flags) {
+  const { install, uninstall } = require(path.join(REPO_ROOT, "statusline", "install.js"));
+  const { getSettingsPath } = require(path.join(REPO_ROOT, "server", "lib", "claude-home.js"));
+  const file = getSettingsPath();
+  const force = Boolean(flags.force);
+  const r = sub === "install" ? install(file, { force }) : uninstall(file, { force });
+  const prev = r.previous ? JSON.stringify(r.previous) : "";
+  switch (r.status) {
+    case "installed":
+      console.log(`${c.green("✔")} statusLine set in ${file}: ${r.command}`);
+      if (prev) console.log(c.dim(`  replaced ${prev} (backup beside the file)`));
+      console.log(c.dim("  Claude Code picks it up on the next prompt."));
+      return;
+    case "unchanged":
+      console.log(`statusLine already set in ${file}: ${r.command}`);
+      return;
+    case "removed":
+      console.log(`${c.green("✔")} statusLine removed from ${file} (backup beside the file)`);
+      return;
+    case "absent":
+      console.log(`No statusLine in ${file}.`);
+      return;
+    case "foreign":
+      console.error(c.red(`✖ ${file} has a statusLine that is not AgentHub's: ${prev}`));
+      console.error(
+        c.dim(
+          `  Re-run with --force to ${sub === "install" ? "replace" : "remove"} it (a backup is kept).`
+        )
+      );
+      process.exitCode = 1;
+  }
+}
+
+// ── Server mode (docs/SERVER-MODE.md) ──────────────────────────────────────
+
+/** The auth module over the SAME database and settings the server reads: the
+ *  repo `.env`, then AgentHub's settings file (a pinned DASHBOARD_DATA_DIR). */
+function serverAuth() {
+  const settingsEnv = require(path.join(REPO_ROOT, "server", "lib", "settings-env.js"));
+  settingsEnv.loadEnvFiles({ owned: [path.join(REPO_ROOT, ".env")] });
+  return { settingsEnv, auth: require(path.join(REPO_ROOT, "server", "lib", "auth.js")) };
+}
+
+/** One password: typed hidden on a terminal, else the first line of stdin. */
+async function askPassword(prompt) {
+  const stdin = process.stdin;
+  if (!stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8").split(/\r?\n/)[0];
+  }
+  process.stdout.write(prompt);
+  return new Promise((resolve, reject) => {
+    let typed = "";
+    const finish = () => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      process.stdout.write("\n");
+    };
+    const onData = (text) => {
+      for (const ch of text) {
+        if (ch === "\r" || ch === "\n") return (finish(), resolve(typed));
+        if (ch === "\u0003") return (finish(), reject(new Error("cancelled")));
+        typed = ch === "\u007f" || ch === "\b" ? typed.slice(0, -1) : typed + ch;
+      }
+    };
+    stdin.setRawMode(true);
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+    stdin.resume();
+  });
+}
+
+/** A new password, typed twice on a terminal. */
+async function newPassword(label) {
+  const first = await askPassword(`${label}: `);
+  if (process.stdin.isTTY && (await askPassword("Again: ")) !== first) {
+    throw new Error("the two passwords differ");
+  }
+  return first;
+}
+
+/** `agenthub server setup|off|status` — turn server mode on or off. */
+async function cmdServer(sub, flags) {
+  const { settingsEnv, auth } = serverAuth();
+  const file = settingsEnv.settingsFilePath();
+  const envNote = (key) => {
+    if (settingsEnv.envOwned.has(key)) {
+      console.log(
+        c.yellow(`! ${key} is also set in the environment or .env, which wins over ${file}`)
+      );
+    }
+  };
+  if (sub === "setup") {
+    if (flags.hostname) {
+      const hosts = String(flags.hostname);
+      if (!/^[a-z0-9.\-:[\],]+$/i.test(hosts)) throw new Error(`bad --hostname: ${hosts}`);
+      settingsEnv.writeSetting("DASHBOARD_ALLOWED_HOSTS", hosts);
+      envNote("DASHBOARD_ALLOWED_HOSTS");
+    }
+    if (!auth.hasAdmin()) {
+      const name = typeof flags.admin === "string" ? flags.admin : "admin";
+      const user = await auth.createUser(
+        name,
+        await newPassword(`Password for admin ${name}`),
+        "admin"
+      );
+      console.log(`${c.green("✔")} admin ${user.username} created`);
+    } else {
+      console.log(c.dim("  an admin already exists — add more with `agenthub users add`"));
+    }
+    settingsEnv.writeSetting("AGENTHUB_MODE", "server");
+    envNote("AGENTHUB_MODE");
+    console.log(`${c.green("✔")} server mode on (${file})`);
+    console.log("  Next:");
+    console.log(
+      "  1. Restart the dashboard: systemctl --user restart agenthub  (or agenthub start)"
+    );
+    console.log(
+      "  2. Serve it over HTTPS through a reverse proxy that keeps the Host header,\n" +
+        "     and run setup with --hostname <that name> — see docs/SERVER-MODE.md."
+    );
+    console.log(
+      c.dim("  Members see only their own workspaces, but every pane still runs as this")
+    );
+    console.log(c.dim("  one Linux account — use it with people you trust (docs/SERVER-MODE.md)."));
+    console.log(
+      c.dim("  Workspaces made before now have no owner: agenthub users assign <id> <user>")
+    );
+    return;
+  }
+  if (sub === "install-system") return installSystem(flags, settingsEnv);
+  if (sub === "tools") {
+    // S3/S4: copy this install's scripts and every installed AI tool under
+    // /opt/agenthub, where every account's pane runs them (the server also
+    // does this at start and after each install/update).
+    const shared = require(path.join(REPO_ROOT, "server", "lib", "shared-tools.js"));
+    await shared.publishApp(REPO_ROOT);
+    const rows = await shared.publishAll();
+    table(
+      ["tool", "shared copy"],
+      rows.map((r) => [
+        r.id,
+        r.error ? c.red(r.error) : `${r.path}${r.copied ? "" : c.dim(" (unchanged)")}`,
+      ])
+    );
+    return;
+  }
+  if (sub === "off") {
+    settingsEnv.writeSetting("AGENTHUB_MODE", "local");
+    envNote("AGENTHUB_MODE");
+    console.log(`${c.green("✔")} server mode off — restart the dashboard. Users are kept.`);
+    return;
+  }
+  if (sub === "status" || sub === undefined) {
+    const users = auth.listUsers();
+    console.log(`mode:     ${auth.isServerMode() ? "server" : "local"}`);
+    console.log(`settings: ${file}`);
+    console.log(
+      `users:    ${users.length} (${users.filter((u) => u.role === "admin").length} admin)`
+    );
+    console.log(c.dim("  a change takes effect when the dashboard restarts"));
+    return;
+  }
+  console.error(
+    c.red(
+      "✖ Usage: agenthub server setup [--hostname name] [--admin name] | install-system [--dry-run|--uninstall] | tools | off | status"
+    )
+  );
+  process.exitCode = 1;
+}
+
+/**
+ * `agenthub server install-system` — one Linux user per account (S3,
+ * docs/SERVER-MODE.md). Run as the HOST account, never as root: it resolves
+ * this install's paths as the host, hands them to the root half
+ * (`scripts/server/install-system.sh`) through ONE `sudo`, points the system
+ * unit at this install, and moves the dashboard from the `systemd --user`
+ * unit to the system one (panes survive: KillMode=process). `--uninstall`
+ * goes back to the user unit.
+ */
+async function installSystem(flags, settingsEnv) {
+  const os = require("node:os");
+  if (process.getuid && process.getuid() === 0) {
+    throw new Error("run this as the account that runs the dashboard, not as root (it uses sudo)");
+  }
+  const which = (bin) =>
+    spawnSync("sh", ["-c", `command -v ${bin}`], { encoding: "utf8" }).stdout.trim();
+  const host = os.userInfo().username;
+  const { getDataDir } = require(path.join(REPO_ROOT, "server", "lib", "claude-home.js"));
+  const data = getDataDir();
+  const port = String(process.env.DASHBOARD_PORT || "4820");
+  const script = path.join(REPO_ROOT, "scripts", "server", "install-system.sh");
+  const args = flags.uninstall
+    ? [script, "--uninstall", "--host", host]
+    : [
+        script,
+        ...["--host", host, "--node", process.execPath, "--root", REPO_ROOT, "--data", data],
+        ...["--port", port, "--tmux", which("tmux"), "--git", which("git")],
+        ...(which("gh") ? ["--gh", which("gh")] : []),
+      ];
+  if (flags["dry-run"]) {
+    console.log(["sudo", "bash", ...args].join(" "));
+    return;
+  }
+  const userUnit = (...a) => spawnSync("systemctl", ["--user", ...a, "agenthub.service"]);
+  // What either unit runs: this install's node and server, with its env.
+  const runtime = path.join(data, "runtime");
+  const clientDist = fs.existsSync(path.join(REPO_ROOT, "client", "dist", "index.html"))
+    ? path.join(REPO_ROOT, "client", "dist")
+    : path.join(runtime, "client-dist");
+  const env = { NODE_ENV: "production", PATH: process.env.PATH || "", DASHBOARD_PORT: port };
+  env.DASHBOARD_CLIENT_DIST = clientDist;
+  if (!fs.existsSync(path.join(REPO_ROOT, "node_modules"))) {
+    env.NODE_PATH = path.join(runtime, "node_modules");
+  }
+  const serverArgv = [process.execPath, path.join(REPO_ROOT, "server", "index.js")];
+  if (flags.uninstall) {
+    if (spawnSync("sudo", ["bash", ...args], { stdio: "inherit" }).status !== 0) {
+      throw new Error("install-system --uninstall failed");
+    }
+    // Repoint the user unit first: the build it named may have been pruned
+    // while the system unit was the one protected.
+    require(path.join(REPO_ROOT, "scripts", "systemd-service.js")).writeUserService({
+      argv: serverArgv,
+      env,
+    });
+    userUnit("enable", "--now");
+    console.log(`${c.green("✔")} back on the systemd --user unit`);
+    return;
+  }
+  if (spawnSync("sudo", ["bash", ...args], { stdio: "inherit" }).status !== 0) {
+    throw new Error("install-system failed — nothing was started");
+  }
+  // The unit reads node, the plugin root and the env from a file this account
+  // owns (the bootstrap repoints it after an update without root).
+  const sys = require(path.join(REPO_ROOT, "scripts", "systemd-system-service.js"));
+  const wrote = sys.writeUserService({ argv: serverArgv, env });
+  if (wrote === "failed" || wrote === "unavailable") {
+    throw new Error(`could not write ${sys.envPath()} (${wrote})`);
+  }
+  settingsEnv.writeSetting(
+    "AGENTHUB_USERS_ROOT",
+    require(path.join(REPO_ROOT, "server", "lib", "linux-accounts.js")).serverConf().usersRoot
+  );
+  // Hand over: the user unit stops (its panes stay), and so does a dashboard
+  // started without one (detached) — else the system unit finds the port
+  // taken and the old process, without the S3 groups, keeps serving.
+  userUnit("disable", "--now");
+  const boot = require(path.join(REPO_ROOT, "scripts", "plugin-bootstrap.js"));
+  const sysUp = () =>
+    spawnSync("systemctl", ["is-active", "agenthub.service"], {
+      encoding: "utf8",
+    }).stdout.trim() === "active";
+  // A re-run while the system unit serves: that server is the one to keep.
+  if (!sysUp()) boot.stopDashboard();
+  for (let i = 0; i < 50 && !sysUp() && boot.livePids().length; i++) {
+    spawnSync("sleep", ["0.2"]);
+  }
+  if (!sysUp() && boot.livePids().length) {
+    throw new Error("a dashboard is still running — stop it first");
+  }
+  if (spawnSync("sudo", ["-n", "systemctl", "enable", "agenthub.service"]).status !== 0) {
+    console.log(c.yellow("! could not enable agenthub.service for boot"));
+  }
+  if (spawnSync("sudo", ["-n", "systemctl", "start", "--no-block", "agenthub.service"]).status) {
+    throw new Error("could not start agenthub.service — `sudo systemctl status agenthub`");
+  }
+  spawnSync("sleep", ["3"]);
+  if (!sysUp()) {
+    throw new Error("agenthub.service did not stay up — `sudo journalctl -u agenthub -n 50`");
+  }
+  console.log(`${c.green("✔")} the dashboard now runs as the system unit agenthub.service`);
+  console.log("  Give the existing users their Linux accounts: agenthub users provision --all");
+  console.log(
+    c.dim("  Log out and back in once: your own session joins groups agenthub/agenthub-proc.")
+  );
+}
+
+/** `agenthub users …` — server mode's accounts, written straight to the DB. */
+async function cmdUsers(sub, positional, flags) {
+  const { auth } = serverAuth();
+  const name = positional[0];
+  const need = () => {
+    if (!name) throw new Error(`usage: agenthub users ${sub} <username>`);
+  };
+  switch (sub) {
+    case undefined:
+    case "list":
+      table(
+        ["id", "username", "role", "state"],
+        auth.listUsers().map((u) => [u.id, u.username, u.role, u.disabled ? "disabled" : "active"])
+      );
+      return;
+    case "add": {
+      need();
+      const role = typeof flags.role === "string" ? flags.role : "developer";
+      const user = await auth.createUser(name, await newPassword(`Password for ${name}`), role);
+      console.log(`${c.green("✔")} ${user.username} added (${user.role})`);
+      return;
+    }
+    case "passwd":
+      need();
+      await auth.setPassword(name, await newPassword(`New password for ${name}`));
+      console.log(`${c.green("✔")} password changed — ${name}'s logins ended`);
+      return;
+    case "role":
+      need();
+      auth.setRole(name, positional[1]);
+      console.log(`${c.green("✔")} ${name} is now ${positional[1]}`);
+      return;
+    case "assign":
+      if (!name || !positional[1]) {
+        throw new Error("usage: agenthub users assign <workspace id> <username>");
+      }
+      auth.assignWorkspace(name, positional[1]);
+      console.log(`${c.green("✔")} workspace ${name} now belongs to ${positional[1]}`);
+      return;
+    case "audit": {
+      const { listAudit } = require(path.join(REPO_ROOT, "server", "lib", "audit.js"));
+      table(
+        ["when", "reader", "owner", "path"],
+        listAudit(typeof flags.limit === "string" ? flags.limit : 50).map((a) => [
+          a.at.replace("T", " ").slice(0, 19),
+          a.reader,
+          a.owner,
+          a.path,
+        ])
+      );
+      return;
+    }
+    case "provision": {
+      // S3: the Linux account of a user made before install-system (or after a
+      // failed create). Idempotent: an existing member account is kept.
+      const linux = require(path.join(REPO_ROOT, "server", "lib", "linux-accounts.js"));
+      if (!linux.s3Enabled()) {
+        throw new Error(
+          "one Linux user per account is not installed (agenthub server install-system)"
+        );
+      }
+      const names = flags.all
+        ? auth
+            .listUsers()
+            .filter((u) => !u.disabled)
+            .map((u) => u.username)
+        : (need(), [name]);
+      const memberClaude = require(path.join(REPO_ROOT, "server", "lib", "member-claude.js"));
+      for (const n of names) {
+        // One user that cannot be provisioned (a name Linux refuses, a folder
+        // already there) is reported and skipped — never the end of the run.
+        try {
+          console.log(`${c.green("✔")} ${linux.provision("create", n)}`);
+        } catch (e) {
+          console.error(c.red(`✖ ${n}: ${e.message}`));
+          process.exitCode = 1;
+          continue;
+        }
+        // Opt-in plugin baseline (/etc/agenthub/plugin-baseline.json); prints per entry.
+        await memberClaude.applyPluginBaseline(n);
+      }
+      return;
+    }
+    case "disable":
+    case "enable":
+      need();
+      auth.setDisabled(name, sub === "disable");
+      console.log(`${c.green("✔")} ${name} ${sub}d`);
+      return;
+    default:
+      console.error(
+        c.red(
+          "✖ Usage: agenthub users list | add <name> [--role admin|analyst|developer] | passwd <name> | role <name> <role> | disable <name> | enable <name> | provision <name>|--all | assign <workspace id> <name> | audit [--limit N]"
+        )
+      );
+      process.exitCode = 1;
+  }
+}
+
+/** `agenthub accounts … --tool codex` — the Codex account pool (server/lib/codex-pool.js). */
+async function cmdCodexAccounts(sub, name, flags) {
+  const pool = require(path.join(REPO_ROOT, "server", "lib", "codex-pool.js"));
+  if (sub === "add") {
+    let added;
+    if (flags["api-key"]) {
+      added = pool.addAccount(name, { apiKey: await askPassword(`OpenAI API key for ${name}: `) });
+    } else if (typeof flags.from === "string") {
+      // A `codex login` home (or its auth.json) — read here, on the host's shell.
+      const from = path.resolve(flags.from);
+      const file = fs.statSync(from).isDirectory() ? path.join(from, "auth.json") : from;
+      added = pool.addAccount(name, { auth: JSON.parse(fs.readFileSync(file, "utf8")) });
+      console.log(c.dim(`  You can delete ${file} now; the pool keeps its own copy.`));
+    } else {
+      throw new Error(
+        "usage: agenthub accounts add <name> --tool codex --api-key | --from <dir>\n" +
+          "  A ChatGPT account: `CODEX_HOME=$(mktemp -d) codex login` signed in as it, then --from that dir."
+      );
+    }
+    console.log(`${c.green("✔")} ${added.name} (${added.kind}) added`);
+    console.log(c.dim("  New Codex sessions now spread over the pool's accounts."));
+    return;
+  }
+  if (sub === "remove") {
+    pool.removeAccount(name);
+    console.log(`${c.green("✔")} ${name} removed — running panes keep it until they exit`);
+    return;
+  }
+  if (sub !== undefined && sub !== "list") {
+    throw new Error("usage: agenthub accounts list | add <name> | remove <name> --tool codex");
+  }
+  pool.resetQuota();
+  table(
+    ["codex account", "kind", "live", "$ 5h", "$ 7d", "quota", "state"],
+    pool
+      .poolStatus()
+      .map((a) => [
+        a.name,
+        a.kind,
+        a.livePanes,
+        a.spend5h.toFixed(2),
+        a.spend7d.toFixed(2),
+        a.quota
+          ? a.quota.windows.map((w) => `${w.label} ${Math.round(w.usedPercent)}%`).join(" ")
+          : "–",
+        a.full ? "full" : "ok",
+      ])
+  );
+}
+
+/** `agenthub accounts …` — the Claude account pool (server/lib/claude-pool.js). */
+async function cmdAccounts(sub, positional, flags = {}) {
+  serverAuth(); // the same settings + database the server reads
+  const pool = require(path.join(REPO_ROOT, "server", "lib", "claude-pool.js"));
+  const name = positional[0];
+  if (sub === "add" || sub === "remove") {
+    if (!name) throw new Error(`usage: agenthub accounts ${sub} <name> [--tool codex]`);
+  }
+  if (flags.tool != null && flags.tool !== "claude" && flags.tool !== "codex") {
+    throw new Error("--tool is claude (the default) or codex");
+  }
+  if (flags.tool === "codex") return cmdCodexAccounts(sub, name, flags);
+  if (sub === "add") {
+    console.log(
+      c.dim("  Run `claude setup-token` signed in as that account, then paste the token.")
+    );
+    const added = pool.addAccount(name, await askPassword(`Token for ${name}: `));
+    console.log(
+      `${c.green("✔")} ${added.name} added — valid until ${added.expiresAt.slice(0, 10)}`
+    );
+    console.log(c.dim("  New Claude sessions now spread over the pool's accounts."));
+    return;
+  }
+  if (sub === "remove") {
+    pool.removeAccount(name);
+    console.log(`${c.green("✔")} ${name} removed — running panes keep it until they exit`);
+    return;
+  }
+  if (sub === undefined || sub === "list") {
+    await pool.refreshQuotas({ force: true });
+    const pct = (w) => (w?.utilization != null ? `${Math.round(w.utilization)}%` : "–");
+    table(
+      ["account", "live", "$ 5h", "$ 7d", "quota 5h", "quota wk", "state"],
+      pool
+        .poolStatus()
+        .map((a) => [
+          a.name,
+          a.livePanes,
+          a.spend5h.toFixed(2),
+          a.spend7d.toFixed(2),
+          pct(a.quota?.fiveHour),
+          pct(a.quota?.sevenDay),
+          a.expired
+            ? "expired"
+            : a.full
+              ? "full"
+              : a.quota?.error
+                ? `no quota (${a.quota.error})`
+                : "ok",
+        ])
+    );
+    const codex = require(path.join(REPO_ROOT, "server", "lib", "codex-pool.js"));
+    if (codex.poolStatus().length) await cmdCodexAccounts("list", null, flags);
+    return;
+  }
+  console.error(
+    c.red("✖ Usage: agenthub accounts list | add <name> | remove <name> [--tool codex]")
+  );
+  process.exitCode = 1;
+}
+
 /** Run one parsed command. Returns the handler's promise; may throw
  *  ServerDownError (for the caller's offline routing) or call process.exit
  *  for usage/validation failures. `cmd === "repl"` is handled by the entry
@@ -3681,8 +4325,18 @@ async function runCommand(argv) {
       return cmdStatus();
     case "start":
       return cmdStart(flags);
+    case "stop":
+      return cmdStop();
+    case "uninstall":
+      return cmdUninstall(flags);
     case "service":
       return cmdService(positional[0], flags);
+    case "server":
+      return cmdServer(positional[0], flags);
+    case "users":
+      return cmdUsers(positional[0], positional.slice(1), flags);
+    case "accounts":
+      return cmdAccounts(positional[0], positional.slice(1), flags);
     case "stats":
       return cmdStats();
     case "kanban":
@@ -3800,6 +4454,18 @@ async function runCommand(argv) {
       process.exitCode = 1;
       return;
     }
+    case "mcp":
+      return require(path.join(REPO_ROOT, "mcp", "server.js")).main();
+    case "statusline":
+      if (rest[0] === "install" || rest[0] === "uninstall") return cmdStatusline(rest[0], flags);
+      if (rest[0]) {
+        console.error("usage: agenthub statusline [install|uninstall [--force]]");
+        process.exitCode = 1;
+        return;
+      }
+      return require(path.join(REPO_ROOT, "statusline", "statusline.js")).main();
+    case "tray":
+      return require(path.join(REPO_ROOT, "scripts", "tray.js")).main();
     case "open":
       return cmdOpen();
     case "version":

client/README.md

@@ -52,13 +52,13 @@ 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/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
+- **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 per-browser preference: `agenthub.terminal.font` = `jetbrains|maple|system` (`lib/terminalFont.ts`, default `jetbrains`), picked in Settings → Appearance and read when a terminal opens
 
-  **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`, `#e8e5da`) and a `.card` is brighter than the page it sits on (`surface-3`, `#f5f3ec`), 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.
+  **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:
-  - **Light mode's hue family is warm, dark mode's is cool.** The light ramp is Claude's own ivory/terracotta (`#e8e5da` → `#fcfbf7`, warm neutrals, warm `--shadow-card`), not Radix slate: a cool near-white page reads as glare at any lightness, because the brightest thing on screen is also the bluest. Dark mode stays slate + blue — a warm accent on a near-black page is a different problem with a different answer.
-  - Light `--accent` is **not** the dark one, in hue or in step. Dark's `#0090ff` is 3.3:1 on white; Claude's brand terracotta `#cc785c` is 3.1:1 on ivory and 3.3:1 under white text, so it works as a large fill and fails as a link or a button label. Light mode uses it three steps down, `#924224` (it was `#a34a28`, which missed 4.5:1 as text on its own selected chip).
+  - **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.
@@ -199,13 +199,17 @@ client/
 │   │   │   ├── 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      # Workflow analytics, rendered in Dashboard → Analytics → Workflow
 │   │   ├── Settings.tsx
@@ -255,7 +259,7 @@ graph TB
     Detail[SessionDetail<br/>agent hierarchy + timeline]
     Feed[ActivityFeed<br/>streaming event log]
     Workflows[Workflows<br/>Analytics → Workflow sub-tab:<br/>lane pipelines + D3 analytics]
-    Settings[SettingsHub /settings/:section<br/>General · Appearance · Notifications<br/>Agents: AI tools, Claude Code, Codex, each catalog tool<br/>Routing: AI Router, Pricing · Git: credentials, worktree suggestions]
+    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 & Settings
@@ -501,6 +505,8 @@ 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={<Navigate to="/?tab=analytics&sub=workflow" replace />} />
@@ -519,7 +525,7 @@ function App() {
 }
 ```
 
-The heavy pages — `Workspace` (xterm, the diff viewer), `SettingsHub` and `SessionDetail` — are `React.lazy` imports in `App.tsx`, each route wrapped in `<Suspense>` (the `Page` helper), so they load on first visit instead of in the initial bundle. `App.tsx` also mounts the app-wide `<Toaster />` and `<ConfirmHost />` once, beside `<GlobalTooltip />`.
+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
 
@@ -787,6 +793,12 @@ 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

client/index.html

@@ -30,7 +30,7 @@
     <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"
@@ -45,23 +45,23 @@
     <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="AgentHub - 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="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="AgentHub - 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 -->
@@ -70,7 +70,7 @@
         "@context": "https://schema.org",
         "@type": "WebApplication",
         "name": "AgentHub",
-        "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.",
+        "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",

client/package.json

@@ -17,6 +17,7 @@
     "@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",

client/public/sw.js

@@ -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

client/src/App.tsx

@@ -38,8 +38,8 @@
  * ## Internal dependencies
  * - `./components/Layout`
  * - `./components/SplashScreen`
- * - `./pages/Dashboard`
- * - `./pages/History`
+ * - `./pages/Dashboard` (lazy)
+ * - `./pages/History` (lazy)
  * - `./pages/SessionDetail` (lazy)
  * - `./pages/SettingsHub` (lazy)
  * - `./pages/Workspace` (lazy)
@@ -64,17 +64,19 @@ import { GlobalTooltip } from "./components/Tooltip";
 import { Toaster } from "./components/Toaster";
 import { ConfirmHost } from "./components/ConfirmHost";
 import { RouteErrorBoundary, reloadOnce } from "./components/RouteErrorBoundary";
-import { Dashboard } from "./pages/Dashboard";
-import { History } from "./pages/History";
 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.
+// 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 }))
@@ -82,6 +84,10 @@ const SettingsHub = lazy(() =>
 const SessionDetail = lazy(() =>
   import("./pages/SessionDetail").then((m) => ({ default: m.SessionDetail }))
 );
+const SnapshotView = lazy(() =>
+  import("./pages/SnapshotView").then((m) => ({ default: m.SnapshotView }))
+);
+const Users = lazy(() => import("./pages/Users").then((m) => ({ default: m.Users })));
 
 function PageFallback() {
   const { t } = useTranslation();
@@ -129,6 +135,10 @@ export default function App() {
     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);
@@ -148,8 +158,22 @@ export default function App() {
         <DocumentTitle />
         <Routes>
           <Route element={<Layout wsConnected={connected} />}>
-            <Route index element={<Dashboard />} />
-            <Route path="sessions" element={<History />} />
+            <Route
+              index
+              element={
+                <Page>
+                  <Dashboard />
+                </Page>
+              }
+            />
+            <Route
+              path="sessions"
+              element={
+                <Page>
+                  <History />
+                </Page>
+              }
+            />
             <Route
               path="sessions/:id"
               element={
@@ -158,6 +182,15 @@ export default function App() {
                 </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"
@@ -177,6 +210,14 @@ export default function App() {
                 </Page>
               }
             />
+            <Route
+              path="users"
+              element={
+                <Page>
+                  <Users />
+                </Page>
+              }
+            />
             <Route
               path="settings/*"
               element={

client/src/components/AlertsNotifications.tsx

@@ -70,6 +70,8 @@ import {
   BellOff,
   Check,
   CheckCheck,
+  ChevronDown,
+  Eye,
   ListChecks,
   Pencil,
   Plus,
@@ -87,9 +89,12 @@ import { ConfirmModal } from "./ConfirmModal";
 import { Checkbox } from "./Checkbox";
 import { FieldHelp } from "./FieldHelp";
 import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "./ContextMenu";
-import { timeAgo } from "../lib/format";
+import { fmtCost, timeAgo } from "../lib/format";
 import { toast } from "../lib/toast";
-import type { AlertEvent, AlertRule, AlertRuleType, WSMessage } from "../lib/types";
+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;
 
@@ -124,6 +129,8 @@ const RULE_TYPES: AlertRuleType[] = [
   "inactivity",
   "status_duration",
   "token_threshold",
+  "cost_threshold",
+  "budget",
 ];
 
 type TabKey = "rules" | "channels" | "activity";
@@ -139,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;
 }
 
@@ -153,6 +165,11 @@ 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",
 };
 
@@ -171,12 +188,28 @@ function formFromRule(rule: AlertRule): RuleFormState {
     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": {
@@ -198,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;
+    }
   }
 }
 
@@ -225,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("%, ") + "%",
+      });
   }
 }
 
@@ -232,7 +285,9 @@ 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[]>([]);
@@ -244,6 +299,9 @@ export function AlertsNotifications() {
   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) => () => {
@@ -288,6 +346,7 @@ export function AlertsNotifications() {
       setLoadingAlerts(false);
     }
   }, [unackedOnly, t]);
+  const [spinning, refreshAlerts] = useSpin(loadAlerts);
 
   const loadMore = useCallback(async () => {
     try {
@@ -305,8 +364,8 @@ export function AlertsNotifications() {
   }, [unackedOnly, alerts.length, t]);
 
   useEffect(() => {
-    loadRules();
-  }, [loadRules]);
+    if (isAdmin) loadRules();
+  }, [loadRules, isAdmin]);
 
   useEffect(() => {
     loadAlerts();
@@ -322,10 +381,35 @@ 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 onPreview = async () => {
+    if (previewing) return;
+    setPreviewing(true);
+    setFormError(null);
+    try {
+      const cooldown = parseInt(form.cooldown_seconds, 10);
+      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);
@@ -333,6 +417,7 @@ export function AlertsNotifications() {
 
   const openEditRule = (rule: AlertRule) => {
     setForm(formFromRule(rule));
+    setPreview(null);
     setEditingId(rule.id);
     setFormError(null);
     setFormOpen(true);
@@ -417,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"),
@@ -434,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">
@@ -680,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">
@@ -701,14 +884,29 @@ export function AlertsNotifications() {
                     </span>
                   )}
                 </label>
-                <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 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>
@@ -825,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
@@ -890,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"
@@ -927,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>
+  );
+}

client/src/components/AuthGate.tsx

@@ -0,0 +1,261 @@
+/**
+ * @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 and `logout`;
+ * `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,
+  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> };
+
+const AuthContext = createContext<AuthValue>({ state: { mode: "local" }, logout: async () => {} });
+
+/** 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,
+    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]);
+
+  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 }}>{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>
+  );
+}

client/src/components/ConfirmModal.tsx

@@ -85,14 +85,14 @@ export function ConfirmModal({
     >
       <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" aria-hidden />

client/src/components/EventReplay.tsx

@@ -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>
+  );
+}

client/src/components/EventTimeline.tsx

@@ -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>
+  );
+}

client/src/components/ImageLightbox.tsx

@@ -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
+  );
+}

client/src/components/Layout.tsx

@@ -12,6 +12,11 @@
  * 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
@@ -46,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.
@@ -76,8 +82,31 @@ 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 { OnboardingWizard } from "./onboarding/OnboardingWizard";
+import { OnboardingTour } from "./onboarding/OnboardingTour";
+
+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)";
@@ -112,7 +141,17 @@ export function Layout({ wsConnected }: LayoutProps) {
   const [drawerOpen, setDrawerOpen] = useState(false);
   const closeDrawer = useCallback(() => setDrawerOpen(false), []);
   const { pathname, search } = useLocation();
-  const sidebarWidth = drawer ? "0rem" : collapsed ? "4.25rem" : "15rem";
+  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]);
@@ -136,7 +175,10 @@ export function Layout({ wsConnected }: LayoutProps) {
         {t("skipToContent")}
       </a>
       <UpdateNotifier />
-      <Sagi />
+      <InterruptedSessionsPrompt />
+      <SagiMount />
+      <OnboardingWizard />
+      <OnboardingTour />
       {drawer && drawerOpen && (
         <div
           aria-hidden
@@ -153,11 +195,52 @@ export function Layout({ wsConnected }: LayoutProps) {
         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 pb-6 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: sidebarWidth,
           width: `calc(100% - ${sidebarWidth})`,

client/src/components/NeedsYouStrip.tsx

@@ -14,6 +14,7 @@ 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";
 
@@ -32,6 +33,9 @@ export function NeedsYouStrip({ compact = false }: { compact?: boolean }) {
         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))
@@ -40,11 +44,14 @@ export function NeedsYouStrip({ compact = false }: { compact?: boolean }) {
 
   useEffect(() => {
     load();
-  }, [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;
 

client/src/components/PathPickButton.tsx

@@ -12,7 +12,7 @@
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
-import { useState } from "react";
+import { useState, type Ref } from "react";
 import { useTranslation } from "react-i18next";
 import { FolderOpen } from "lucide-react";
 import { api } from "../lib/api";
@@ -27,12 +27,15 @@ export function PathPickButton({
   start,
   onPick,
   showLabel = false,
+  buttonRef,
 }: {
   kind?: "dir" | "file";
   /** The field's current value — the picker opens there. */
   start?: string;
   onPick: (path: string) => void;
   showLabel?: boolean;
+  /** Lets a field beside it open the same picker (a click on an empty path). */
+  buttonRef?: Ref<HTMLButtonElement>;
 }) {
   const { t } = useTranslation(["lanes"]);
   const [busy, setBusy] = useState(false);
@@ -61,6 +64,7 @@ export function PathPickButton({
   return (
     <>
       <button
+        ref={buttonRef}
         type="button"
         onClick={pick}
         disabled={busy}

client/src/components/RemoteSources.tsx

@@ -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
@@ -97,6 +98,8 @@ const EMPTY_FORM: RemoteSourceInput = {
   ssh_port: null,
   identity_file: "",
   remote_home: "",
+  sync_codex: false,
+  remote_codex_home: "",
   enabled: true,
 };
 
@@ -219,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);
@@ -242,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 {
@@ -591,6 +598,31 @@ export function RemoteSources() {
               </p>
             </div>
           </div>
+          <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 }))}
@@ -674,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
@@ -689,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>
                     )}

client/src/components/Sagi/PetMenu.tsx

@@ -28,6 +28,7 @@ import {
 } 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 =
@@ -50,6 +51,8 @@ export function PetMenu({
   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(() => {
@@ -133,6 +136,7 @@ export function PetMenu({
           </button>
           {list?.featured.map((f) => {
             const have = installed.get(f.id);
+            if (!have && !isAdmin) return null;
             return (
               <button
                 key={f.id}
@@ -173,48 +177,54 @@ export function PetMenu({
                 <span className="min-w-0 truncate">{p.displayName}</span>
                 {mark(p.id)}
               </button>
-              <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>
+              {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" />
-          <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>
+          {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"

client/src/components/Sagi/PetSprite.tsx

@@ -1,9 +1,14 @@
 /**
  * @file PetSprite.tsx
  * @description The mascot wearing a custom pet (`/api/pets`). A Codex pet is
- * a 1536×1872 spritesheet — 8 columns × 9 rows of 192×208 frames, one row per
- * animation state (idle, run right, run left, waving, jumping, failed,
- * waiting, running, review) — played one row at a time by Sagi's mood; an
+ * 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, and 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
@@ -16,9 +21,29 @@ import { api } from "../../lib/api";
 import type { Mood } from "./brain";
 
 const CELL = { w: 192, h: 208 };
-const SHEET = { cols: 8, rows: 9 };
-/** Frames in each row of the Codex atlas. */
-const FRAMES = [6, 8, 8, 4, 5, 8, 6, 6, 6];
+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,
@@ -30,11 +55,16 @@ const ROW: Record<Mood, number> = {
   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 };
 
 export function PetSprite({
   id,
   kind,
   mood,
+  action,
+  gaze,
   size,
   reducedMotion,
   onBroken,
@@ -42,31 +72,55 @@ export function PetSprite({
   id: string;
   kind: "codex" | "image";
   mood: Mood;
+  action?: PetAction | 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 = ROW[mood] ?? 0;
-  const [frame, setFrame] = useState(0);
+  const row = action ? ACTION_ROW[action] : (ROW[mood] ?? 0);
+  const sleeping = !action && 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(() => {
-    setFrame(0);
+    setCell({ of: row, row, col: 0 });
     if (kind !== "codex" || reducedMotion) return;
-    const timer = window.setInterval(
-      () => setFrame((f) => (f + 1) % (FRAMES[row] ?? 1)),
-      mood === "sleeping" ? 400 : 125
-    );
-    return () => window.clearInterval(timer);
-  }, [kind, row, mood, reducedMotion]);
+    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 timer = 0;
+    // `i` always indexes `list`: it wraps at its end.
+    const tick = () => {
+      timer = window.setTimeout(() => {
+        if (++i === list.length) {
+          i = 0;
+          if (MOMENTS.has(row)) list = play(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
@@ -87,11 +141,18 @@ export function PetSprite({
       />
     );
   }
+  const pose = gaze != null && rows > GAZE_ROW && !action && 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={row}
+      data-row={shown.row}
       aria-hidden
       style={{
         width: Math.round(CELL.w * scale),
@@ -99,8 +160,8 @@ export function PetSprite({
         margin: "0 auto",
         backgroundImage: `url("${url}")`,
         backgroundRepeat: "no-repeat",
-        backgroundSize: `${SHEET.cols * CELL.w * scale}px ${SHEET.rows * CELL.h * scale}px`,
-        backgroundPosition: `${-frame * CELL.w * scale}px ${-row * CELL.h * scale}px`,
+        backgroundSize: `${COLS * CELL.w * scale}px ${rows * CELL.h * scale}px`,
+        backgroundPosition: `${-shown.col * CELL.w * scale}px ${-shown.row * CELL.h * scale}px`,
       }}
     />
   );

client/src/components/Sagi/Sagi.tsx

@@ -1,11 +1,15 @@
 /**
  * @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.
+ * @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.
  *   Owns the open/closed panel 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: an unmatched Ask query starts a claude session in
@@ -73,6 +77,7 @@ import {
   type ReactNode,
 } from "react";
 import { useNavigate } from "react-router-dom";
+import { useSettingsHref } from "../../lib/settingsLink";
 import { useTranslation } from "react-i18next";
 import { SagiAvatar } from "./SagiAvatar";
 import { PetSprite } from "./PetSprite";
@@ -81,6 +86,7 @@ import { SpeechBubble } from "./SpeechBubble";
 import { SagiPanel } from "./SagiPanel";
 import { useSagiBrain } from "./useSagiBrain";
 import { useSagiPosition } from "./useSagiPosition";
+import { useSagiEnabled } from "./SagiMount";
 import { matchIntent } from "./intents";
 import { sagiPrefs } from "./prefs";
 import { api } from "../../lib/api";
@@ -195,24 +201,30 @@ function SagiFlyout({
   );
 }
 
+/** Renders nothing — and runs no hook below — while the mascot is disabled. */
 export function Sagi() {
+  return useSagiEnabled() ? <SagiBody /> : null;
+}
+
+function SagiBody() {
   const { t } = useTranslation("settings");
-  const [enabled, setEnabled] = useState(() => sagiPrefs.getEnabled());
   const [pet, setPet] = useState(() => sagiPrefs.getPet());
   const [size, setSize] = useState(() => sagiPrefs.getSize());
   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(size);
 
-  // Keep enabled, the pet and its size in sync with Settings / other tabs.
+  // 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(() => {
-        setEnabled(sagiPrefs.getEnabled());
         setPet(sagiPrefs.getPet());
         setSize(sagiPrefs.getSize());
       }),
@@ -222,7 +234,6 @@ export function Sagi() {
   // ⌘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(() => {
-    if (!enabled) return;
     const onKey = (e: KeyboardEvent) => {
       if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "b") {
         if (isEditable(e.target) || isEditable(document.activeElement)) return;
@@ -234,7 +245,33 @@ export function Sagi() {
     };
     window.addEventListener("keydown", onKey);
     return () => window.removeEventListener("keydown", onKey);
-  }, [enabled]);
+  }, []);
+
+  // 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) => {
@@ -278,8 +315,6 @@ export function Sagi() {
     [brain, navigate, t]
   );
 
-  if (!enabled) return null;
-
   const anchor: Anchor = {
     left: place.left,
     top: place.top,
@@ -315,7 +350,7 @@ export function Sagi() {
             onClose={() => setMenu(false)}
             onSettings={() => {
               setMenu(false);
-              navigate("/settings/appearance#pet");
+              navigate(href("appearance#pet"));
             }}
           />
         </SagiFlyout>
@@ -328,9 +363,12 @@ export function Sagi() {
       )}
 
       <button
+        ref={btn}
         className="sagi-avatar-btn"
         data-dragging={place.dragging ? "1" : "0"}
         style={{ left: place.left, top: place.top, width: size, height: size }}
+        onPointerEnter={() => setHover(true)}
+        onPointerLeave={() => setHover(false)}
         onPointerDown={place.onPointerDown}
         onPointerMove={place.onPointerMove}
         onPointerUp={place.onPointerUp}
@@ -358,6 +396,9 @@ export function Sagi() {
             id={pet.id}
             kind={pet.kind}
             mood={brain.mood}
+            // Dragged → runs that way; hovered → waves (Codex's pet does both).
+            action={place.moving ? `run-${place.moving}` : hover ? "wave" : null}
+            gaze={gaze}
             size={size}
             reducedMotion={reducedMotion}
             // Deleted elsewhere, or unreadable: back to Sagi.

client/src/components/Sagi/SagiAvatar.tsx

@@ -36,7 +36,7 @@
  * - `skills/file-headers/` — mandatory `@author` header policy.
  * ============================================================================= */
 
-import { useEffect, useRef, useState } from "react";
+import { memo, useEffect, useRef } from "react";
 import type { Mood } from "./brain";
 
 interface SagiAvatarProps {
@@ -76,10 +76,21 @@ 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,
+}: 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 +100,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 +116,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)
@@ -202,7 +213,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 +237,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 +803,4 @@ export function SagiAvatar({ mood, reducedMotion, size = 68 }: SagiAvatarProps)
       </g>
     </svg>
   );
-}
+});

client/src/components/Sagi/SagiMount.tsx

@@ -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>
+  );
+}

client/src/components/Sagi/__tests__/Pets.test.tsx

@@ -93,7 +93,9 @@ describe("PetSprite", () => {
     // 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(130));
+    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
@@ -108,6 +110,98 @@ describe("PetSprite", () => {
     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

client/src/components/Sagi/__tests__/Sagi.test.tsx

@@ -5,7 +5,16 @@
  */
 
 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";
@@ -192,3 +201,22 @@ describe("Sagi widget", () => {
     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();
+  });
+});

client/src/components/Sagi/useSagiBrain.ts

@@ -168,7 +168,10 @@ export function useSagiBrain(): SagiBrain {
   // Advance the clock so timed moods (stuck/sleeping, and exit from
   // happy/worried) re-evaluate without needing a new event.
   useEffect(() => {
-    const id = setInterval(() => setTick(Date.now()), 1000);
+    // Hidden tab: no re-render; the first visible tick catches the mood up.
+    const id = setInterval(() => {
+      if (document.visibilityState === "visible") setTick(Date.now());
+    }, 1000);
     return () => clearInterval(id);
   }, []);
 

client/src/components/Sagi/useSagiPosition.ts

@@ -7,6 +7,8 @@
  *   viewport fraction so it survives resizes). A small movement threshold tells
  *   a drag apart from a tap so dragging never opens the panel. The arrow keys
  *   move a focused avatar too (WCAG 2.5.7): ←/→ dock it to an edge, ↑/↓ step it.
+ *   `moving` names the way it is heading — while dragged (cleared once the
+ *   pointer rests) and during the glide to its edge — so a pet can run that way.
  *   It never rests over the fixed bottom status bar; by default it docks
  *   bottom-right just above it.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
@@ -83,6 +85,8 @@ const DRAG_THRESHOLD = 5;
 const STATUS_BAR = 24;
 // One arrow-key step, in px.
 const KEY_STEP = 40;
+// A held but unmoving drag stops running after this; also the snap glide's length.
+const MOVE_SETTLE_MS = 300;
 
 const vw = () => (typeof window !== "undefined" ? window.innerWidth : 1024);
 const vh = () => (typeof window !== "undefined" ? window.innerHeight : 768);
@@ -109,6 +113,8 @@ export interface SagiPlacement {
   /** True when the avatar sits in the lower half - flyouts open upward. */
   openUp: boolean;
   dragging: boolean;
+  /** The way the avatar is moving horizontally right now, if it is. */
+  moving: "left" | "right" | null;
   onPointerDown: (e: ReactPointerEvent) => void;
   onPointerMove: (e: ReactPointerEvent) => void;
   onPointerUp: (e: ReactPointerEvent) => void;
@@ -123,6 +129,15 @@ export function useSagiPosition(size: number = SAGI_SIZE): SagiPlacement {
   const [pos, setPos] = useState<SagiPos>(() => sagiPrefs.getPos() ?? defaultPos());
   const [drag, setDrag] = useState<{ left: number; top: number } | null>(null);
   const [, force] = useState(0); // re-derive resting coords on resize
+  const [moving, setMoving] = useState<"left" | "right" | null>(null);
+  const moveTimer = useRef(0);
+  const lastX = useRef(0);
+  const heading = useCallback((dir: "left" | "right" | null) => {
+    window.clearTimeout(moveTimer.current);
+    setMoving(dir);
+    if (dir) moveTimer.current = window.setTimeout(() => setMoving(null), MOVE_SETTLE_MS);
+  }, []);
+  useEffect(() => () => window.clearTimeout(moveTimer.current), []);
 
   const draggedRef = useRef(false);
   const startRef = useRef<{ px: number; py: number; left: number; top: number } | null>(null);
@@ -152,6 +167,7 @@ export function useSagiPosition(size: number = SAGI_SIZE): SagiPlacement {
         /* capture unsupported - window-free fallback still works via props */
       }
       startRef.current = { px: e.clientX, py: e.clientY, left: screen.left, top: screen.top };
+      lastX.current = e.clientX;
       movedRef.current = false;
     },
     [screen.left, screen.top]
@@ -172,8 +188,14 @@ export function useSagiPosition(size: number = SAGI_SIZE): SagiPlacement {
       );
       liveRef.current = { left, top };
       setDrag({ left, top });
+      // Ignore a pixel of jitter; a steady push keeps re-arming the settle timer.
+      const stepX = e.clientX - lastX.current;
+      if (Math.abs(stepX) >= 2) {
+        lastX.current = e.clientX;
+        heading(stepX > 0 ? "right" : "left");
+      }
     },
-    [size]
+    [size, heading]
   );
 
   const onPointerUp = useCallback(
@@ -193,12 +215,15 @@ export function useSagiPosition(size: number = SAGI_SIZE): SagiPlacement {
         sagiPrefs.setPos(next);
         setPos(next);
         setDrag(null); // leave drag mode; resting coords (with transition) take over
+        // Run along the glide to the edge, when there is a real distance to cover.
+        const glide = restingScreen(next, size).left - live.left;
+        heading(Math.abs(glide) > size / 2 ? (glide > 0 ? "right" : "left") : null);
       }
       liveRef.current = null;
       startRef.current = null;
       movedRef.current = false;
     },
-    [size]
+    [size, heading]
   );
 
   const onKeyDown = useCallback(
@@ -214,10 +239,11 @@ export function useSagiPosition(size: number = SAGI_SIZE): SagiPlacement {
       }
       if (!next) return;
       e.preventDefault();
+      if (next.side !== pos.side) heading(next.side);
       sagiPrefs.setPos(next);
       setPos(next);
     },
-    [pos, size]
+    [pos, size, heading]
   );
 
   const consumeDrag = useCallback(() => {
@@ -233,6 +259,7 @@ export function useSagiPosition(size: number = SAGI_SIZE): SagiPlacement {
     side: pos.side,
     openUp: screen.top + size / 2 > vh() / 2,
     dragging: drag !== null,
+    moving,
     onPointerDown,
     onPointerMove,
     onPointerUp,

client/src/components/Select.tsx

@@ -3,7 +3,8 @@
  * @description Generic styled dropdown that replaces native `<select>` elements
  * for consistent cross-platform rendering. Native macOS/Chromium selects reserve
  * checkmark space inconsistently; this control aligns labels, flips above the
- * trigger when viewport space is tight, and marks the chosen option with accent
+ * trigger when space is tight — in its split pane (`data-menu-bounds`, see
+ * `menuRoom`) or else the viewport — and marks the chosen option with accent
  * color plus a Lucide check.
  *
  * ## Accessibility — WAI-ARIA "listbox button"
@@ -74,6 +75,14 @@
 import { useEffect, useId, useRef, useState, type ReactNode } from "react";
 import { ChevronDown, Check } from "lucide-react";
 
+/** Room above and below `r` (the trigger's rect) for a menu it opens: inside
+ *  the nearest `data-menu-bounds` box — a split pane, whose neighbour paints
+ *  over anything crossing its edge — else the viewport. */
+export function menuRoom(el: Element, r: DOMRect): { above: number; below: number } {
+  const box = el.closest("[data-menu-bounds]")?.getBoundingClientRect();
+  return { above: r.top - (box?.top ?? 0), below: (box?.bottom ?? window.innerHeight) - r.bottom };
+}
+
 /** Single option in a {@link Select} list. */
 export interface SelectOption<T extends string> {
   /** Stored value emitted via `onChange`. */
@@ -84,6 +93,8 @@ export interface SelectOption<T extends string> {
   hint?: string;
   /** Optional leading icon, shown in the trigger and the list. */
   icon?: ReactNode;
+  /** Draw a rule above this option: it starts a group of its own. */
+  divider?: boolean;
 }
 
 /** Props for {@link Select}. */
@@ -142,9 +153,11 @@ export function Select<T extends string>({
     const idx = options.findIndex((o) => o.value === value);
     setActive(idx >= 0 ? idx : 0);
     if (buttonRef.current) {
-      const rect = buttonRef.current.getBoundingClientRect();
-      const below = window.innerHeight - rect.bottom;
-      setOpenUp(below < 288 && rect.top > below);
+      const { above, below } = menuRoom(
+        buttonRef.current,
+        buttonRef.current.getBoundingClientRect()
+      );
+      setOpenUp(below < 288 && above > below);
     }
     listRef.current?.focus({ preventScroll: true });
     // eslint-disable-next-line react-hooks/exhaustive-deps -- only on open
@@ -272,6 +285,8 @@ export function Select<T extends string>({
                 onClick={() => choose(opt)}
                 onMouseEnter={() => setActive(idx)}
                 className={`w-full cursor-pointer text-left px-3 py-1.5 transition-colors ${
+                  opt.divider ? "mt-1 border-t border-border pt-2" : ""
+                } ${
                   isActive ? "bg-accent/15" : isSelected ? "bg-surface-3" : "hover:bg-surface-3"
                 }`}
               >

client/src/components/SessionOverview.tsx

@@ -76,22 +76,27 @@ import type { Agent, Session, SessionStats } from "../lib/types";
 interface SessionOverviewProps {
   session: Session;
   agents: Agent[];
+  /** Frozen stats (a session snapshot): shown as given, never fetched or refreshed. */
+  stats?: SessionStats;
 }
 
 /** Throttle window for stats refresh - coalesces bursts of hook events into one fetch. */
-const REFRESH_THROTTLE_MS = 1000;
+const REFRESH_THROTTLE_MS = 5000;
 
 /** Compact tile used in the top stat row. */
 function StatTile({
   label,
   value,
   hint,
+  help,
   icon,
   tone = "default",
 }: {
   label: string;
   value: React.ReactNode;
   hint?: string;
+  /** Plain-language explanation, shown as the label's tooltip. */
+  help?: string;
   icon: React.ReactNode;
   tone?: "default" | "violet" | "emerald" | "amber" | "rose" | "cyan" | "blue";
 }) {
@@ -118,9 +123,14 @@ function StatTile({
 
   return (
     <div className={`rounded-lg border px-3 py-2.5 ${palette}`}>
-      <div className="flex items-center gap-1.5 text-[10px] uppercase tracking-wider text-fg-muted">
+      <div
+        className={`flex items-center gap-1.5 text-[10px] uppercase tracking-wider text-fg-muted${help ? " cursor-help" : ""}`}
+        title={help}
+      >
         <span className={iconTone}>{icon}</span>
-        {label}
+        <span className={help ? "underline decoration-dotted underline-offset-2" : undefined}>
+          {label}
+        </span>
       </div>
       <div className="mt-1 font-mono text-lg font-semibold text-fg-primary leading-tight">
         {value}
@@ -160,18 +170,19 @@ function ToolUsageRow({ toolName, count, max }: { toolName: string; count: numbe
   );
 }
 
-export function SessionOverview({ session, agents }: SessionOverviewProps) {
+export function SessionOverview({ session, agents, stats: frozen }: SessionOverviewProps) {
   const { t } = useTranslation("sessions");
-  const [stats, setStats] = useState<SessionStats | null>(null);
+  const [fetched, setStats] = useState<SessionStats | null>(null);
+  const stats = frozen ?? fetched;
   const fetchingRef = useRef(false);
 
   // Tick clock every 30s so a still-active session's "duration" tile stays current.
   const [now, setNow] = useState(() => Date.now());
   useEffect(() => {
-    if (session.status !== "active") return;
+    if (frozen || session.status !== "active") return;
     const id = window.setInterval(() => setNow(Date.now()), 30_000);
     return () => window.clearInterval(id);
-  }, [session.status]);
+  }, [frozen, session.status]);
 
   // A refresh asked for while one is in flight is not dropped: it runs once
   // when the current one settles (that is the throttle's trailing call).
@@ -198,6 +209,7 @@ export function SessionOverview({ session, agents }: SessionOverviewProps) {
 
   // Initial load + reload when the session id changes.
   useEffect(() => {
+    if (frozen) return;
     fetchStats();
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [session.id]);
@@ -206,6 +218,7 @@ export function SessionOverview({ session, agents }: SessionOverviewProps) {
   // stream still refreshes) and again after a reconnect.
   useLiveRefresh(() => void fetchStats(), {
     throttleMs: REFRESH_THROTTLE_MS,
+    enabled: !frozen,
     match: (msg) => {
       if (isRemoteDataRefreshMessage(msg)) return true;
       if (
@@ -305,6 +318,7 @@ export function SessionOverview({ session, agents }: SessionOverviewProps) {
       <div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-2.5">
         <StatTile
           label={t("overview.events")}
+          help={t("common:insights.help.events")}
           value={stats.total_events.toLocaleString()}
           hint={
             eventRate !== null && eventRate > 0
@@ -317,6 +331,7 @@ export function SessionOverview({ session, agents }: SessionOverviewProps) {
         />
         <StatTile
           label={t("overview.toolCalls")}
+          help={t("common:insights.help.toolCalls")}
           value={toolCallCount.toLocaleString()}
           hint={distinctTools > 0 ? t("overview.unique", { count: distinctTools }) : undefined}
           icon={<Wrench className="w-3 h-3" />}
@@ -324,6 +339,7 @@ export function SessionOverview({ session, agents }: SessionOverviewProps) {
         />
         <StatTile
           label={t("overview.subagents")}
+          help={t("common:insights.help.subagents")}
           value={stats.agents.subagent.toLocaleString()}
           hint={
             stats.agents.main > 0 ? t("overview.plusMain", { count: stats.agents.main }) : undefined
@@ -333,12 +349,14 @@ export function SessionOverview({ session, agents }: SessionOverviewProps) {
         />
         <StatTile
           label={t("overview.compactions")}
+          help={t("common:insights.help.compactions")}
           value={stats.agents.compaction.toLocaleString()}
           icon={<Layers className="w-3 h-3" />}
           tone="blue"
         />
         <StatTile
           label={t("overview.errors")}
+          help={t("common:insights.help.errors")}
           value={stats.error_count.toLocaleString()}
           icon={<AlertTriangle className="w-3 h-3" />}
           tone={stats.error_count > 0 ? "rose" : "default"}
@@ -473,7 +491,10 @@ export function SessionOverview({ session, agents }: SessionOverviewProps) {
       {totalTokens > 0 && (
         <div className="rounded-lg border border-surface-3 bg-surface-2/60 p-3.5">
           <div className="flex items-center justify-between mb-2.5">
-            <h3 className="text-xs font-semibold text-fg-secondary uppercase tracking-wider flex items-center gap-1.5">
+            <h3
+              className="text-xs font-semibold text-fg-secondary uppercase tracking-wider flex items-center gap-1.5 cursor-help"
+              title={t("common:insights.help.tokenFlow")}
+            >
               <Coins className="w-3.5 h-3.5 text-status-warning" />
               {t("overview.tokenFlow")}
             </h3>

client/src/components/Sidebar.tsx

@@ -1,6 +1,6 @@
 /**
  * @file Sidebar.tsx
- * @description The app's left sidebar: the brand, the navigation links and the workspace list, with Settings and the collapse/expand button pinned to its foot. It also owns the connection details modal (opened from the status bar), which carries the version and the update check — the sidebar itself has no footer, language or theme controls (those live in Settings → General / Appearance). The collapsed state is kept in localStorage; with none stored it starts collapsed below Tailwind's `lg`. Below `md` the Layout turns it into an off-canvas drawer (`drawer` prop): a modal dialog with the shared `useDialog` focus contract.
+ * @description The app's left sidebar: the brand, the navigation links and the workspace list, with Settings (on a workspace, that workspace's Settings tab — `lib/settingsLink.ts`) and the collapse/expand button pinned to its foot. It also owns the connection details modal (opened from the status bar), which carries the version and the update check — the sidebar itself has no footer, language or theme controls (those live in Settings → General / Appearance). The collapsed state is kept in localStorage; with none stored it starts collapsed below Tailwind's `lg`. Below `md` the Layout turns it into an off-canvas drawer (`drawer` prop): a modal dialog with the shared `useDialog` focus contract.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 /* =============================================================================
@@ -49,7 +49,8 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
-import { NavLink } from "react-router-dom";
+import { NavLink, useLocation } from "react-router-dom";
+import { settingsHref } from "../lib/settingsLink";
 import { useTranslation } from "react-i18next";
 import { useDialog } from "../hooks/useDialog";
 import {
@@ -69,9 +70,13 @@ import {
   ChevronUp,
   ChevronDown,
   FolderTree,
+  LogOut,
+  UsersRound,
 } from "lucide-react";
 import type { LucideIcon } from "lucide-react";
 import { api } from "../lib/api";
+import { BRAND_LOGO, BRAND_MARK } from "../lib/brand";
+import { useAuth, usePermissions } from "./AuthGate";
 import { eventBus } from "../lib/eventBus";
 import { WorkspaceTree } from "./WorkspaceTree";
 import type { UpdateStatusPayload, WSMessage } from "../lib/types";
@@ -85,13 +90,6 @@ const NAV_KEYS = [
   { to: "/sessions", icon: FolderOpen, key: "nav:sessions" },
 ] as const;
 
-// SmartGift wordmark, replacing the old text subtitle. Remote URLs: the logo is
-// owned by the brand, not vendored here — a machine with no network shows the
-// alt text instead.
-const BRAND_LOGO =
-  "https://smg-services.s3.ap-southeast-1.amazonaws.com/smartgift/assets/logo/logo-main.png";
-const BRAND_MARK = "https://smartgift.vn/favicon.ico";
-
 const STORAGE_KEY = "sidebar-collapsed";
 const STATS_STORAGE_KEY = "sidebar-connection-stats";
 const RECENT_EVENTS_CAP = 8;
@@ -170,6 +168,10 @@ interface SidebarProps {
   onUpdateAvailableChange?: (available: boolean) => void;
   /** Set on a narrow viewport: the sidebar is an off-canvas drawer. */
   drawer?: { open: boolean; onClose: () => void };
+  /** Expanded width in px, chosen by dragging its edge (see Layout). */
+  width?: number;
+  /** True while that edge is dragged: no width transition lagging the pointer. */
+  resizing?: boolean;
 }
 
 export function Sidebar({
@@ -180,8 +182,19 @@ export function Sidebar({
   onConnectionOpenChange,
   onUpdateAvailableChange,
   drawer,
+  width = 240,
+  resizing = false,
 }: SidebarProps) {
   const { t } = useTranslation();
+  const auth = useAuth();
+  // On a workspace Settings opens as its tab (lib/settingsLink.ts), so the
+  // link's own match (the path) cannot tell when it is the one on screen.
+  const location = useLocation();
+  const settingsOn =
+    location.pathname.startsWith("/settings") ||
+    new URLSearchParams(location.search).has("settings");
+  // Checking for (and applying) an update acts on the host: an admin's.
+  const canUpdate = usePermissions().isAdmin;
   const asideRef = useRef<HTMLElement>(null);
   const drawerOpen = Boolean(drawer?.open);
   useDialog(drawerOpen, asideRef, drawer?.onClose);
@@ -423,8 +436,9 @@ export function Sidebar({
                 ? "visible translate-x-0 shadow-2xl transition-transform"
                 : "invisible -translate-x-full transition-[transform,visibility]"
             }`
-          : `z-30 transition-[width] duration-200 ${collapsed ? "w-[4.25rem]" : "w-60"}`
+          : `z-30 duration-200 ${resizing ? "" : "transition-[width]"} ${collapsed ? "w-[4.25rem]" : ""}`
       }`}
+      style={drawer || collapsed ? undefined : { width }}
     >
       <div className="px-3 py-4 border-b border-border flex-shrink-0">
         <div className="flex flex-col items-center justify-center">
@@ -454,7 +468,15 @@ export function Sidebar({
           user knows there's more to reach without inspecting the scrollbar. */}
       <div className="flex-1 min-h-0 relative flex">
         <nav ref={navRef} className="flex-1 overflow-y-auto overflow-x-hidden px-2 py-2 space-y-px">
-          {NAV_KEYS.map(({ to, icon: Icon, key }) => {
+          {[
+            ...NAV_KEYS,
+            // Server mode: the Users page, for an admin or analyst.
+            ...(auth.state.mode === "server" &&
+            auth.state.user &&
+            auth.state.user.role !== "developer"
+              ? [{ to: "/users", icon: UsersRound, key: "nav:users" }]
+              : []),
+          ].map(({ to, icon: Icon, key }) => {
             const label = t(key);
             return (
               <NavLink
@@ -475,6 +497,7 @@ export function Sidebar({
             <button
               type="button"
               onClick={onToggle}
+              data-testid="sidebar-tree-rail"
               title={t("lanes:tree.title")}
               aria-label={t("lanes:tree.title")}
               className="flex w-full items-center justify-center rounded-md px-2 py-2 text-fg-secondary transition-colors hover:bg-surface-3 hover:text-fg-primary"
@@ -517,13 +540,29 @@ export function Sidebar({
         }`}
       >
         <NavLink
-          to="/settings"
+          to={settingsHref("", location)}
           title={collapsed ? t("nav:settings") : undefined}
-          className={(p) => `${navClass(p)} ${collapsed ? "" : "flex-1"}`}
+          className={() => `${navClass({ isActive: settingsOn })} ${collapsed ? "" : "flex-1"}`}
         >
           <Settings className="w-4 h-4 flex-shrink-0" />
           {!collapsed && <span>{t("nav:settings")}</span>}
         </NavLink>
+        {auth.state.mode === "server" && auth.state.user && (
+          <button
+            type="button"
+            onClick={() => void auth.logout()}
+            title={`${t("common:auth.signedInAs", {
+              name: auth.state.user.username,
+              role: auth.state.user.role,
+            })} — ${t("common:auth.logout")}`}
+            aria-label={t("common:auth.logout")}
+            className={`inline-flex items-center justify-center rounded-md text-fg-muted transition-colors hover:bg-surface-3 hover:text-fg-primary ${
+              collapsed ? "py-2" : "h-8 w-8 flex-shrink-0"
+            }`}
+          >
+            <LogOut className="h-4 w-4" />
+          </button>
+        )}
         <button
           type="button"
           onClick={onToggle}
@@ -558,7 +597,7 @@ export function Sidebar({
           checking,
           available: updateAvailable,
           failed: checkError,
-          onCheck: onCheckUpdates,
+          onCheck: canUpdate ? onCheckUpdates : undefined,
         }}
         onResetStats={() => {
           eventCountRef.current = 0;
@@ -600,7 +639,8 @@ interface ConnectionStatusModalProps {
     checking: boolean;
     available: boolean;
     failed: boolean;
-    onCheck: () => void;
+    /** Absent for a user who may not update (server mode, not an admin). */
+    onCheck?: () => void;
   };
   onResetStats: () => void;
 }
@@ -742,18 +782,20 @@ function ConnectionStatusModal({
                   {update.title}
                 </p>
               </div>
-              <button
-                type="button"
-                onClick={update.onCheck}
-                disabled={update.checking}
-                className="btn-ghost shrink-0 text-xs disabled:opacity-60"
-              >
-                <RefreshCw
-                  className={`h-3.5 w-3.5 ${update.checking ? "animate-spin" : ""}`}
-                  aria-hidden
-                />
-                {t("nav:checkForUpdates")}
-              </button>
+              {update.onCheck && (
+                <button
+                  type="button"
+                  onClick={update.onCheck}
+                  disabled={update.checking}
+                  className="btn-ghost shrink-0 text-xs disabled:opacity-60"
+                >
+                  <RefreshCw
+                    className={`h-3.5 w-3.5 ${update.checking ? "animate-spin" : ""}`}
+                    aria-hidden
+                  />
+                  {t("nav:checkForUpdates")}
+                </button>
+              )}
             </div>
           </Section>
 

client/src/components/Skeleton.tsx

@@ -27,7 +27,6 @@
  * ## Public surface
  * - `Skeleton` — exported API; see TSDoc on the symbol for behavior.
  * - `StatValueSkeleton` — exported API; see TSDoc on the symbol for behavior.
- * - `TextSkeleton` — exported API; see TSDoc on the symbol for behavior.
  * - `TableRowSkeleton` — exported API; see TSDoc on the symbol for behavior.
  *
  * ## Testing pointers
@@ -52,11 +51,6 @@
  *   the signature and return type as stable unless release notes say otherwise.
  *   When behavior changes, update the `@file` overview and relevant tests.
  *
- * **TextSkeleton**
- *   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.
- *
  * **TableRowSkeleton**
  *   Part of this module's public contract. Downstream imports should treat
  *   the signature and return type as stable unless release notes say otherwise.
@@ -112,19 +106,6 @@ export function StatValueSkeleton({ className = "" }: { className?: string }) {
   return <Skeleton className={`h-7 w-20 align-middle ${className}`} />;
 }
 
-/**
- * Single-line text placeholder. Good for trend/sub labels.
- */
-export function TextSkeleton({
-  className = "",
-  width = "w-16",
-}: {
-  className?: string;
-  width?: string;
-}) {
-  return <Skeleton className={`h-3 ${width} align-middle ${className}`} />;
-}
-
 /**
  * Full table-row skeleton for tabular pages. Caller passes the column count so
  * the skeleton lines up under existing headers.

client/src/components/SnapshotButton.tsx

@@ -0,0 +1,84 @@
+/**
+ * @file SnapshotButton.tsx
+ * @description The session analysis page's **Snapshot** action: confirms with a
+ * "redact file paths" choice, freezes the session through `POST
+ * /api/snapshots`, copies the `/snapshot/<token>` link and offers it inline.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useState } from "react";
+import { Link } from "react-router-dom";
+import { useTranslation } from "react-i18next";
+import { Camera } from "lucide-react";
+import { api } from "../lib/api";
+import { ConfirmModal } from "./ConfirmModal";
+import { Checkbox } from "./Checkbox";
+import { CopyButton } from "./event-views/primitives";
+
+export function snapshotUrl(token: string): string {
+  return `${window.location.origin}/snapshot/${token}`;
+}
+
+export function SnapshotButton({ sessionId }: { sessionId: string }) {
+  const { t } = useTranslation("sessions");
+  const [open, setOpen] = useState(false);
+  const [redact, setRedact] = useState(true);
+  const [busy, setBusy] = useState(false);
+  const [token, setToken] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const create = async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      const { snapshot } = await api.snapshots.create(sessionId, { filePaths: redact });
+      setToken(snapshot.token);
+      navigator.clipboard?.writeText(snapshotUrl(snapshot.token)).catch(() => undefined);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+      setOpen(false);
+    }
+  };
+
+  return (
+    <div className="flex flex-wrap items-center justify-end gap-1">
+      {token && (
+        <span className="inline-flex items-center gap-1 text-xs text-fg-secondary">
+          <Link to={`/snapshot/${token}`} className="text-accent hover:underline">
+            {t("snapshot.open")}
+          </Link>
+          <CopyButton text={snapshotUrl(token)} />
+        </span>
+      )}
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        title={t("snapshot.hint")}
+        className="btn-ghost text-xs"
+      >
+        <Camera className="h-4 w-4" />
+        {t("snapshot.create")}
+      </button>
+      {error && (
+        <p role="alert" className="basis-full text-right text-[11px] text-status-danger">
+          {error}
+        </p>
+      )}
+      <ConfirmModal
+        open={open}
+        title={t("snapshot.title")}
+        message={t("snapshot.body")}
+        confirmLabel={t("snapshot.confirm")}
+        cancelLabel={t("snapshot.cancel")}
+        destructive={false}
+        busy={busy}
+        onConfirm={() => void create()}
+        onCancel={() => setOpen(false)}
+      >
+        <Checkbox checked={redact} onChange={setRedact} label={t("snapshot.redactPaths")} />
+      </ConfirmModal>
+    </div>
+  );
+}

client/src/components/StatCard.tsx

@@ -77,6 +77,8 @@ interface StatCardProps {
   loading?: boolean;
   /** Drill-in: the whole card links here (e.g. the list the number counts). */
   to?: string;
+  /** Plain-language explanation of the metric, shown as the label's tooltip. */
+  help?: string;
 }
 
 /**
@@ -92,11 +94,15 @@ export function StatCard({
   raw,
   loading = false,
   to,
+  help,
 }: StatCardProps) {
   const body = (
     <>
       <div className="flex items-center justify-between gap-3 mb-3">
-        <span className="text-xs font-medium text-fg-muted uppercase tracking-wider truncate">
+        <span
+          className={`text-xs font-medium text-fg-muted uppercase tracking-wider truncate${help ? " cursor-help underline decoration-dotted underline-offset-2" : ""}`}
+          title={help}
+        >
           {label}
         </span>
         <Icon className={`w-5 h-5 flex-shrink-0 ${accentColor}`} />

client/src/components/StatusBar.tsx

@@ -23,18 +23,27 @@
 import { Fragment, useCallback, useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { useTranslation } from "react-i18next";
-import { useLocation } from "react-router-dom";
-import { RefreshCw, RotateCcw, Wifi, WifiOff } from "lucide-react";
+import { Link, useLocation } from "react-router-dom";
+import { RefreshCw, Wifi, WifiOff } from "lucide-react";
 import { api, type RunHandle } from "../lib/api";
-import type { CostResult, ToolQuota } from "../lib/types";
+import type { BudgetStatus, CostResult, ToolQuota } from "../lib/types";
 import { fmt, fmtCostFull, formatModelName, timeAgo } from "../lib/format";
 import { AiToolIcon } from "./AiToolIcon";
 import { useLiveRefresh } from "../hooks/useLiveRefresh";
+import { useSpin } from "../hooks/useSpin";
 import { LIVE_RUNS_EVENT, selectedFrom } from "./WorkspaceTree";
 
 const COST_POLL_MS = 30_000;
 const QUOTA_POLL_MS = 5 * 60_000;
-const QUOTA_TOOL_LABEL: Record<ToolQuota["id"], string> = { claude: "Claude", codex: "Codex" };
+const QUOTA_TOOL_LABEL: Record<ToolQuota["id"], string> = {
+  claude: "Claude",
+  codex: "Codex",
+  antigravity: "Antigravity",
+  cursor: "Cursor",
+  grok: "Grok",
+  kimi: "Kimi",
+  opencode: "OpenCode Go",
+};
 
 function localDate(d = new Date()): string {
   const pad = (n: number) => String(n).padStart(2, "0");
@@ -121,6 +130,8 @@ function quotaMeta(q: ToolQuota, t: (k: string, o?: Record<string, unknown>) =>
 const QUOTA_ERROR_KEY: Record<string, string> = {
   ELIVEEXPIRED: "statusBar.quotaExpired",
   EPROFILEEXPIRED: "statusBar.quotaProfileExpired",
+  EWRONGACCOUNT: "statusBar.quotaWrongAccount",
+  ETOKENEXPIRED: "statusBar.quotaTokenExpired",
 };
 
 /** One account: its name, sign-in line, then a row per window with its reset. */
@@ -131,6 +142,14 @@ function QuotaAccount({ q, many }: { q: ToolQuota; many: boolean }) {
     <div data-testid="status-bar-quota-account" className="min-w-0">
       <div className="flex items-center gap-1.5">
         <span className="truncate font-medium">{q.label || q.account}</span>
+        {q.plan && (
+          <span
+            data-testid="status-bar-quota-plan"
+            className="shrink-0 rounded bg-surface-4 px-1 text-[10px] capitalize leading-4 text-fg-secondary"
+          >
+            {q.plan}
+          </span>
+        )}
         {many && q.active !== false && (
           <span className="shrink-0 rounded bg-accent-solid/15 px-1 text-[10px] leading-4 text-accent">
             {t("statusBar.quotaActive")}
@@ -143,12 +162,17 @@ function QuotaAccount({ q, many }: { q: ToolQuota; many: boolean }) {
           {t(QUOTA_ERROR_KEY[q.error] ?? "statusBar.quotaFailed")}
         </div>
       ) : (
-        <div className="mt-1 grid grid-cols-[2.75rem_1fr_2.25rem_4rem] items-center gap-x-2 gap-y-0.5 tabular-nums">
-          {q.windows.map((w) => {
+        <div className="mt-1 grid grid-cols-[2.75rem_1fr_2.25rem_auto] items-center gap-x-2 gap-y-0.5 tabular-nums">
+          {q.windows.map((w, i) => {
             const p = Math.round(w.usedPercent ?? 0);
             const resets = untilText(w.resetsAt);
             return (
-              <Fragment key={w.label}>
+              <Fragment key={`${w.group ?? ""}-${w.label}`}>
+                {w.group && w.group !== q.windows[i - 1]?.group && (
+                  <span className="col-span-4 mt-0.5 truncate text-[10px] text-fg-muted">
+                    {w.group}
+                  </span>
+                )}
                 <span className="text-fg-muted">
                   {t(`statusBar.quotaWindow.${w.label}`, { defaultValue: w.label })}
                 </span>
@@ -159,16 +183,9 @@ function QuotaAccount({ q, many }: { q: ToolQuota; many: boolean }) {
                   />
                 </span>
                 <span className={`text-right ${quotaTone(p)}`}>{p}%</span>
-                <span className="flex items-center justify-end gap-1 text-fg-muted">
-                  {resets && (
-                    <>
-                      <RotateCcw className="h-3 w-3" aria-hidden />
-                      <span aria-hidden>{resets}</span>
-                      <span className="sr-only">
-                        {t("statusBar.quotaResets", { time: resets })}
-                      </span>
-                    </>
-                  )}
+                {/* In words: a ↻ glyph here read as a Refresh button. */}
+                <span className="text-right text-fg-muted">
+                  {resets && t("statusBar.quotaResets", { time: resets })}
                 </span>
               </Fragment>
             );
@@ -208,7 +225,7 @@ function QuotaPanel({
       onMouseLeave={onLeave}
       onFocus={onEnter}
       onBlur={onLeave}
-      className="fixed bottom-7 right-2 z-[9999] w-[19rem] max-w-[calc(100vw-1rem)] rounded-lg border border-border bg-surface-2 px-3 py-2.5 text-[11px] leading-snug text-fg-primary shadow-lg shadow-black/20"
+      className="fixed bottom-7 right-2 z-[9999] max-h-[calc(100vh-2.5rem)] w-[19rem] max-w-[calc(100vw-1rem)] overflow-y-auto rounded-lg border border-border bg-surface-2 px-3 py-2.5 text-[11px] leading-snug text-fg-primary shadow-lg shadow-black/20"
     >
       <div className="mb-2 font-semibold">{t("statusBar.quotaTitle")}</div>
       {groups.map(([id, list]) => (
@@ -264,15 +281,15 @@ function QuotaChips() {
     closeTimer.current = window.setTimeout(() => setOpen(false), 200);
   };
   useEffect(() => () => window.clearTimeout(closeTimer.current), []);
-  const [refreshing, setRefreshing] = useState(false);
-  const load = useCallback((force = false) => {
-    if (force) setRefreshing(true);
-    api.pricing
-      .quota(force)
-      .then((r) => setTools(r.tools))
-      .catch(() => undefined)
-      .finally(() => force && setRefreshing(false));
-  }, []);
+  const load = useCallback(
+    (force = false) =>
+      api.pricing
+        .quota(force)
+        .then((r) => setTools(r.tools))
+        .catch(() => undefined),
+    []
+  );
+  const [refreshing, refresh] = useSpin(() => load(true));
   useVisiblePoll(load, QUOTA_POLL_MS, [load]);
   if (!tools.length) return null;
   return (
@@ -281,7 +298,7 @@ function QuotaChips() {
         type="button"
         data-testid="status-bar-quota"
         data-tip-off
-        onClick={() => load(true)}
+        onClick={refresh}
         onMouseEnter={show}
         onMouseLeave={hide}
         onFocus={show}
@@ -313,7 +330,7 @@ function QuotaChips() {
           tools={tools}
           onEnter={show}
           onLeave={hide}
-          onRefresh={() => load(true)}
+          onRefresh={refresh}
           refreshing={refreshing}
         />
       )}
@@ -342,6 +359,8 @@ export function StatusBar({
   const [laneCost, setLaneCost] = useState<CostResult | null>(null);
   const [sessionCost, setSessionCost] = useState<CostResult | null>(null);
   const [runs, setRuns] = useState<RunHandle[]>([]);
+  // The budget furthest past one of its thresholds, if any.
+  const [budget, setBudget] = useState<BudgetStatus | null>(null);
   const location = useLocation();
   const shown = selectedFrom(location.pathname, location.search);
   const lane = shown.lane;
@@ -381,6 +400,13 @@ export function StatusBar({
         .totalCost({ date: localDate() })
         .then((r) => live && setToday(r))
         .catch(() => undefined);
+      api.budgets
+        .status()
+        .then(({ budgets }) => {
+          const hit = budgets.filter((b) => b.crossed.length > 0).sort((a, b) => b.pct - a.pct);
+          if (live) setBudget(hit[0] ?? null);
+        })
+        .catch(() => undefined);
       if (lane !== null) {
         api.pricing
           .totalCost({ lane })
@@ -470,6 +496,20 @@ export function StatusBar({
           r={sessionCost}
         />
       )}
+      {budget && (
+        <Link
+          to="/?tab=analytics&sub=cost"
+          data-testid="status-bar-budget"
+          title={t("statusBar.budgetTitle", {
+            name: budget.name,
+            spend: usd(budget.spend),
+            limit: usd(budget.config.limit_usd ?? 0),
+          })}
+          className={`tabular-nums hover:underline ${budget.pct >= 100 ? "text-status-danger" : "text-status-warning"}`}
+        >
+          {t("statusBar.budget", { pct: Math.round(budget.pct) })}
+        </Link>
+      )}
       <QuotaChips />
     </footer>
   );

client/src/components/UpdateNotifier.tsx

@@ -22,8 +22,8 @@
  *
  * ## State sources
  * - Initial fetch via `api.updates.status()` on mount.
- * - Background re-check via `api.updates.check()` every hour
- *   ({@link AUTO_CHECK_INTERVAL_MS}), plus the manual "Check now" button.
+ * - No client-side background re-check: the server checks on its own
+ *   schedule and broadcasts `update_status`; "Check now" stays manual.
  * - Live refresh from WebSocket `update_status` events on {@link eventBus}.
  *
  * ## Dismissal persistence
@@ -85,15 +85,14 @@ import { Download, X, Copy, Check, RefreshCw, Zap, ExternalLink } from "lucide-r
 import { api } from "../lib/api";
 import { eventBus } from "../lib/eventBus";
 import { copyText } from "../lib/clipboard";
+import { toast } from "../lib/toast";
 import { useDialog } from "../hooks/useDialog";
 import type { UpdateStatusPayload, WSMessage } from "../lib/types";
+import { usePermissions } from "./AuthGate";
 
 /** `localStorage` key storing the dismissed release tag (or upstream SHA). */
 const DISMISS_KEY = "agent-monitor-update-dismissed-sha";
 
-/** How often to silently re-check for updates in the background. */
-const AUTO_CHECK_INTERVAL_MS = 60 * 60 * 1000;
-
 /** Situations `POST /api/updates/apply` will actually act on. Mirrors the
  *  server: `release_available` / `tracking_canonical` / `fork_or_diverged_tracking`
  *  go through a git fast-forward, and `plugin_managed` goes through the detached
@@ -127,6 +126,7 @@ function loadDismissedSha(): string | null {
  * @returns `null` when no update is available or this release was dismissed.
  */
 export function UpdateNotifier() {
+  const { isAdmin } = usePermissions();
   const { t } = useTranslation("updates");
   const [status, setStatus] = useState<UpdateStatusPayload | null>(null);
   const [dismissedSha, setDismissedSha] = useState<string | null>(loadDismissedSha);
@@ -171,19 +171,6 @@ export function UpdateNotifier() {
     });
   }, [syncFromPayload]);
 
-  // Background re-check every hour, on top of the initial mount fetch and the
-  // manual "Check now" button — so a long-lived tab notices an update without
-  // the user having to click anything.
-  useEffect(() => {
-    const id = setInterval(() => {
-      api.updates
-        .check()
-        .then(syncFromPayload)
-        .catch(() => {});
-    }, AUTO_CHECK_INTERVAL_MS);
-    return () => clearInterval(id);
-  }, [syncFromPayload]);
-
   useEffect(() => {
     // An explicit "Check for updates" undoes both kinds of close.
     const handler = () => {
@@ -205,7 +192,9 @@ export function UpdateNotifier() {
     status?.latest_release ||
     status?.remote_sha ||
     (installed ? `installed:${installed.root}` : null);
+  // Updating replaces the host's install: only an admin is offered it.
   const show = Boolean(
+    isAdmin &&
     status?.update_available &&
     dismissKey &&
     dismissedSha !== dismissKey &&
@@ -264,22 +253,41 @@ export function UpdateNotifier() {
    *   stretch, so polling naively would get a 200 from the process we are
    *   waiting to replace and reload onto the same old bundle.
    */
-  const pollUntilBack = useCallback((requireDownFirst = false) => {
-    let sawDown = !requireDownFirst;
-    const attempt = () => {
-      api.updates
-        .status()
-        .then(() => {
-          if (sawDown) window.location.reload();
-          else setTimeout(attempt, 1500);
-        })
-        .catch(() => {
-          sawDown = true;
-          setTimeout(attempt, 1500);
-        });
-    };
-    setTimeout(attempt, 1500);
-  }, []);
+  const pollUntilBack = useCallback(
+    (requireDownFirst = false, fromVersion: string | null = null) => {
+      let sawDown = !requireDownFirst;
+      // Its own verdicts only: an older plugin-update.json is still on disk
+      // until this chain writes one (5 s slack for a clock a little behind).
+      const since = Date.now() - 5000;
+      const attempt = () => {
+        api.updates
+          .status()
+          .then((s) => {
+            const v = s.last_plugin_update;
+            const mine = !!v?.finished_at && Date.parse(v.finished_at) >= since;
+            // A failed step, or nothing to pull, leaves the OLD server up: it
+            // never goes down, so waiting for that spun "Restarting…" forever.
+            if (requireDownFirst && v && mine && (v.ok === false || v.step === "already_current")) {
+              syncFromPayload(s);
+              setRestarting(false);
+              if (v.ok) toast.info(t("pluginAlreadyCurrent"));
+              return;
+            }
+            // A new version answering is back too, even if a poll never
+            // landed in the short gap between the old server and the new one.
+            const moved = !!fromVersion && !!s.local_version && s.local_version !== fromVersion;
+            if (sawDown || moved) window.location.reload();
+            else setTimeout(attempt, 1500);
+          })
+          .catch(() => {
+            sawDown = true;
+            setTimeout(attempt, 1500);
+          });
+      };
+      setTimeout(attempt, 1500);
+    },
+    [syncFromPayload, t]
+  );
 
   const applyNow = async () => {
     if (applying || restarting) return;
@@ -292,7 +300,7 @@ export function UpdateNotifier() {
         setRestarting(true);
         // mode "plugin": the old server lingers while the chain installs, so
         // only treat a reachable server as "back" after it has gone away once.
-        pollUntilBack(result.mode === "plugin");
+        pollUntilBack(result.mode === "plugin", status?.local_version ?? null);
         return;
       }
       setError(
@@ -330,7 +338,7 @@ export function UpdateNotifier() {
           longest label is a whole sentence ("restarting the dashboard…"). */}
       <div
         ref={panelRef}
-        className="w-full max-w-2xl card shadow-2xl animate-slide-up overflow-hidden"
+        className="w-full max-w-2xl max-h-full flex flex-col card shadow-2xl animate-slide-up overflow-hidden"
       >
         {/* Header */}
         <div className="flex items-start justify-between gap-3 px-5 py-4 border-b border-border">
@@ -370,7 +378,7 @@ export function UpdateNotifier() {
         </div>
 
         {/* Body */}
-        <div className="px-5 py-4 space-y-3">
+        <div className="min-h-0 overflow-y-auto px-5 py-4 space-y-3">
           <p className="text-sm text-fg-secondary leading-relaxed">
             {pluginManaged ? t("pluginAutoNote") : release ? t("releaseLead") : t("lead")}
           </p>
@@ -455,7 +463,10 @@ export function UpdateNotifier() {
           ) : null}
 
           {error ? (
-            <p className="text-xs text-status-danger" role="alert">
+            <p
+              className="text-xs text-status-danger whitespace-pre-wrap break-words max-h-48 overflow-auto"
+              role="alert"
+            >
               {error}
             </p>
           ) : null}

client/src/components/WorkspaceTree.tsx

@@ -6,21 +6,36 @@
  * workspace — or `+` on its row — opens its home (`/workspace?lane=<id>`); a
  * live tab is opened from its session row. Live status comes from the shared
  * lane list (`useLanes`), live panes from `GET /api/run`, re-read whenever a
- * lane's status or session moves and handed over by the Workspace page's own
- * poll (`LIVE_RUNS_EVENT`). Owns its own Add-workspace and
- * destructive modals so the row menu works from any page. Which rows are
- * expanded lives in `projectTreePrefs.ts` (`expanded`).
+ * lane's status or session moves (at most every 3 s) and handed over by the
+ * Workspace page's own poll (`LIVE_RUNS_EVENT`). Owns its own Add-workspace and
+ * destructive modals (lazy-loaded on first open) so the row menu works from any page. Which rows are
+ * expanded lives in `projectTreePrefs.ts` (`expanded`). Server mode, admin or
+ * analyst: EVERY workspace, grouped under its owner (`owner_name`; yours
+ * first, no owner last, groups foldable — `collapsedOwners`); one this user
+ * may not change (`canEditLane`) is read only — no menu, no new session, and a
+ * session opens its analysis page (`/sessions/<id>`), never a pane.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState, type DragEvent } from "react";
+import {
+  lazy,
+  Suspense,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type DragEvent,
+} from "react";
 import { useTranslation } from "react-i18next";
 import { useLocation, useNavigate } from "react-router-dom";
-import { Plus, Search } from "lucide-react";
+import { ChevronDown, ChevronRight, Plus, Search } from "lucide-react";
 import { api, type CwdSuggestion, type RunHandle } from "../lib/api";
 import type { Lane } from "../lib/types";
 import { useLanes } from "../hooks/useLanes";
+import { useAuth, usePermissions } from "./AuthGate";
 import { useAiTools } from "../hooks/useAiTools";
+import { useThrottledValue } from "../hooks/useThrottledValue";
 import {
   insertionIndex,
   moveBefore,
@@ -33,8 +48,15 @@ import { useProjectTreePrefs, writeProjectTreePrefs } from "../lib/projectTreePr
 import { LANE_DRAG_TYPE, WorkspaceRow, isLaneDrag, workspaceName } from "./lanes/WorkspaceRow";
 import { WorkspaceSessionList } from "./lanes/WorkspaceSessionList";
 import { WorkspaceRowMenu, type WorkspaceMenuAction } from "./lanes/WorkspaceRowMenu";
-import { AddLaneModal } from "./lanes/AddLaneModal";
-import { DestructiveLaneModal } from "./lanes/DestructiveLaneModal";
+
+// The sidebar is in the entry chunk; its two modals (and the run form the add
+// modal pulls in) load when first opened.
+const AddLaneModal = lazy(() =>
+  import("./lanes/AddLaneModal").then((m) => ({ default: m.AddLaneModal }))
+);
+const DestructiveLaneModal = lazy(() =>
+  import("./lanes/DestructiveLaneModal").then((m) => ({ default: m.DestructiveLaneModal }))
+);
 
 /** The workspace (and attached run) the Workspace page shows, from its URL. */
 /** The workspace, pane run and replayed session the URL names (Workspace page only). */
@@ -54,6 +76,11 @@ export function WorkspaceTree() {
   const location = useLocation();
   const selected = selectedFrom(location.pathname, location.search);
   const { lanes, refresh: refreshLanes } = useLanes();
+  const { state: auth } = useAuth();
+  const { seesAll, canEditLane } = usePermissions();
+  const meId = auth.mode === "server" ? (auth.user?.id ?? null) : null;
+  // Server mode staff see every user's workspaces, so the list says whose.
+  const grouped = auth.mode === "server" && seesAll;
   const prefs = useProjectTreePrefs();
   const [liveRuns, setLiveRuns] = useState<RunHandle[]>([]);
   const [query, setQuery] = useState("");
@@ -72,8 +99,12 @@ export function WorkspaceTree() {
   // A slot-0 pane starts, ends or learns its session id exactly when a lane's
   // status or session moves, so that is when the live-pane list is re-read;
   // the Workspace page also hands over every run list it polls (a tab in
-  // slots 1–3 moves no lane column).
-  const runKey = lanes.map((l) => `${l.id}:${l.status}:${l.session_id}:${l.run_id}`).join(",");
+  // slots 1–3 moves no lane column). Throttled: with two sessions in one
+  // workspace these columns flip on every hook, and each flip was a GET.
+  const runKey = useThrottledValue(
+    lanes.map((l) => `${l.id}:${l.status}:${l.session_id}:${l.run_id}`).join(","),
+    3000
+  );
   useEffect(() => {
     let live = true;
     api.run
@@ -111,10 +142,17 @@ export function WorkspaceTree() {
   const tools = useMemo(() => [...new Set(lanes.map((l) => l.tool))], [lanes]);
   const toolFilter =
     tools.length > 1 && prefs.tool && tools.includes(prefs.tool) ? prefs.tool : null;
-  const sorted = useMemo(
-    () => sortByStoredOrder(lanes, order).filter((l) => !toolFilter || l.tool === toolFilter),
-    [lanes, order, toolFilter]
-  );
+  const sorted = useMemo(() => {
+    const list = sortByStoredOrder(lanes, order).filter(
+      (l) => !toolFilter || l.tool === toolFilter
+    );
+    if (!grouped) return list;
+    // Stable: each owner's workspaces keep the stored order inside the group.
+    const rank = (l: Lane) => (l.owner_id == null ? 2 : l.owner_id === meId ? 0 : 1);
+    return [...list].sort(
+      (a, b) => rank(a) - rank(b) || (a.owner_name ?? "").localeCompare(b.owner_name ?? "")
+    );
+  }, [lanes, order, toolFilter, grouped, meId]);
   const q = query.trim().toLowerCase();
   const nameHit = (l: Lane) =>
     workspaceName(l).toLowerCase().includes(q) || l.cwd.toLowerCase().includes(q);
@@ -291,42 +329,90 @@ export function WorkspaceTree() {
       )}
 
       <div ref={listRef} className="space-y-px px-1">
-        {sorted.map((lane, i) => (
-          <div key={lane.id} className="relative">
-            {dropAt === i && <DropLine />}
-            {visible(lane) && (
-              <WorkspaceRow
-                lane={lane}
-                index={i}
-                selected={selected.lane === lane.id && !selected.run && !selected.session}
-                expanded={expanded(lane.id)}
-                renaming={renamingId === lane.id}
-                onSelect={() => {
-                  select(lane.id);
-                  if (!expanded(lane.id)) setExpanded(lane.id, true);
-                }}
-                onToggle={() => setExpanded(lane.id, !expanded(lane.id))}
-                onNewSession={() => select(lane.id)}
-                onReorder={(from, to) => reorder((ids) => moveLane(ids, from, to))}
-                onMenu={(x, y) => setMenu({ lane, x, y })}
-                onRenameStart={() => setRenamingId(lane.id)}
-                onRenameEnd={(title) => void rename(lane, title)}
-              />
-            )}
-            {expanded(lane.id) && (
-              <WorkspaceSessionList
-                lane={lane}
-                liveRuns={liveRuns}
-                // A workspace found by its name shows all of its sessions.
-                query={q && nameHit(lane) ? "" : query}
-                selectedRunId={selected.lane === lane.id ? selected.run : null}
-                selectedSessionId={selected.lane === lane.id ? selected.session : null}
-                onMatches={q ? (n) => onMatches(lane.id, n) : undefined}
-                hidden={!visible(lane)}
-              />
-            )}
-          </div>
-        ))}
+        {sorted.map((lane, i) => {
+          const owner = ownerKey(lane);
+          // A search opens every group, like it opens every workspace.
+          const folded = grouped && !q && !!prefs.collapsedOwners[owner];
+          const readOnly = !canEditLane(lane);
+          const ownerLabel =
+            lane.owner_id == null
+              ? t("tree.noOwner")
+              : lane.owner_id === meId
+                ? t("tree.ownerYou", { name: lane.owner_name ?? `#${lane.owner_id}` })
+                : (lane.owner_name ?? `#${lane.owner_id}`);
+          const groupStart = grouped && (i === 0 || ownerKey(sorted[i - 1] ?? lane) !== owner);
+          const groupShown = sorted.some((l) => ownerKey(l) === owner && visible(l));
+          return (
+            <div key={lane.id} className="relative">
+              {groupStart && groupShown && (
+                <button
+                  type="button"
+                  data-testid={`workspace-owner-${owner}`}
+                  aria-expanded={!folded}
+                  title={t("tree.ownerToggle", { name: ownerLabel })}
+                  onClick={() =>
+                    writeProjectTreePrefs({
+                      collapsedOwners: { ...prefs.collapsedOwners, [owner]: !folded },
+                    })
+                  }
+                  className={`flex w-full items-center gap-1 rounded px-1 py-1 text-left text-[11px] font-medium text-fg-muted hover:text-fg-primary ${i === 0 ? "" : "mt-2"}`}
+                >
+                  {folded ? (
+                    <ChevronRight className="h-3 w-3 shrink-0" />
+                  ) : (
+                    <ChevronDown className="h-3 w-3 shrink-0" />
+                  )}
+                  <span
+                    aria-hidden
+                    className="flex h-4 w-4 shrink-0 items-center justify-center rounded-full bg-surface-4 text-[9px] font-semibold uppercase text-fg-secondary"
+                  >
+                    {lane.owner_name?.[0] ?? "?"}
+                  </span>
+                  <span className="truncate">{ownerLabel}</span>
+                  <span className="ml-auto shrink-0 tabular-nums">
+                    {sorted.filter((l) => ownerKey(l) === owner).length}
+                  </span>
+                </button>
+              )}
+              {dropAt === i && <DropLine />}
+              {visible(lane) && !folded && (
+                <WorkspaceRow
+                  lane={lane}
+                  index={i}
+                  readOnly={readOnly ? t("tree.readOnly", { name: ownerLabel }) : undefined}
+                  selected={selected.lane === lane.id && !selected.run && !selected.session}
+                  expanded={expanded(lane.id)}
+                  renaming={renamingId === lane.id}
+                  onSelect={() => {
+                    // A read-only workspace has no home to open: it only unfolds.
+                    if (readOnly) return setExpanded(lane.id, !expanded(lane.id));
+                    select(lane.id);
+                    if (!expanded(lane.id)) setExpanded(lane.id, true);
+                  }}
+                  onToggle={() => setExpanded(lane.id, !expanded(lane.id))}
+                  onNewSession={() => select(lane.id)}
+                  onReorder={(from, to) => reorder((ids) => moveLane(ids, from, to))}
+                  onMenu={(x, y) => setMenu({ lane, x, y })}
+                  onRenameStart={() => setRenamingId(lane.id)}
+                  onRenameEnd={(title) => void rename(lane, title)}
+                />
+              )}
+              {expanded(lane.id) && !folded && (
+                <WorkspaceSessionList
+                  lane={lane}
+                  liveRuns={liveRuns}
+                  readOnly={readOnly}
+                  // A workspace found by its name shows all of its sessions.
+                  query={q && nameHit(lane) ? "" : query}
+                  selectedRunId={selected.lane === lane.id ? selected.run : null}
+                  selectedSessionId={selected.lane === lane.id ? selected.session : null}
+                  onMatches={q ? (n) => onMatches(lane.id, n) : undefined}
+                  hidden={!visible(lane)}
+                />
+              )}
+            </div>
+          );
+        })}
         {dropAt === sorted.length && (
           <div className="relative">
             <DropLine />
@@ -349,32 +435,39 @@ export function WorkspaceTree() {
           onAction={(a) => onMenuAction(menu.lane, a)}
         />
       )}
-      {destructive && (
-        <DestructiveLaneModal
-          lane={destructive.lane}
-          action={destructive.action}
-          open
-          onClose={() => setDestructive(null)}
-          onConfirm={(body) => void confirmDestructive(body)}
-        />
-      )}
-      <AddLaneModal
-        open={addOpen}
-        cwdSuggestions={cwdSuggestions}
-        prefill={addPrefill}
-        onClose={() => {
-          setAddOpen(false);
-          setAddPrefill(null);
-        }}
-        onAdded={(lane) => {
-          void refreshLanes();
-          select(lane.id);
-        }}
-      />
+      <Suspense fallback={null}>
+        {destructive && (
+          <DestructiveLaneModal
+            lane={destructive.lane}
+            action={destructive.action}
+            open
+            onClose={() => setDestructive(null)}
+            onConfirm={(body) => void confirmDestructive(body)}
+          />
+        )}
+        {addOpen && (
+          <AddLaneModal
+            open
+            cwdSuggestions={cwdSuggestions}
+            prefill={addPrefill}
+            onClose={() => {
+              setAddOpen(false);
+              setAddPrefill(null);
+            }}
+            onAdded={(lane) => {
+              void refreshLanes();
+              select(lane.id);
+            }}
+          />
+        )}
+      </Suspense>
     </section>
   );
 }
 
+/** A workspace's owner group: its user id, or "none". */
+const ownerKey = (l: Lane) => (l.owner_id == null ? "none" : String(l.owner_id));
+
 /** Where a dragged workspace would land: a line on its parent's top edge. */
 function DropLine() {
   return (

client/src/components/__tests__/AlertsNotifications.roles.test.tsx

@@ -0,0 +1,60 @@
+/**
+ * @file AlertsNotifications.roles.test.tsx
+ * @description Server mode, not an admin: alert rules and channels fire for
+ * every user, so neither tab is shown nor loaded, and an analyst's feed offers
+ * Acknowledge only on alerts the server marks theirs (`can_ack`).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+
+const rulesList = vi.fn(async () => ({ rules: [] }));
+const alert = (id: number, can_ack: boolean) => ({
+  id,
+  rule_id: "r1",
+  rule_name: `rule ${id}`,
+  rule_type: "error_rate",
+  session_id: null,
+  agent_id: null,
+  message: `boom ${id}`,
+  details: null,
+  triggered_at: "2026-10-08T00:00:00.000Z",
+  acknowledged_at: null,
+  can_ack,
+});
+vi.mock("../../lib/api", () => ({
+  api: {
+    alerts: {
+      rules: { list: () => rulesList() },
+      list: vi.fn(async () => ({
+        alerts: [alert(1, true), alert(2, false)],
+        total: 2,
+        unacked: 2,
+      })),
+      ack: vi.fn(),
+      ackAll: vi.fn(),
+    },
+  },
+}));
+vi.mock("../AuthGate", () => ({
+  usePermissions: () => ({ isAdmin: false, seesAll: true, canEditLane: () => false }),
+}));
+
+import { AlertsNotifications } from "../AlertsNotifications";
+
+describe("AlertsNotifications for a non-admin", () => {
+  it("shows only the feed, and Acknowledge only where the server allows it", async () => {
+    render(
+      <MemoryRouter>
+        <AlertsNotifications />
+      </MemoryRouter>
+    );
+    expect(await screen.findByText("boom 2")).toBeInTheDocument();
+    expect(screen.getAllByRole("button", { name: /^acknowledge$/i })).toHaveLength(1);
+    expect(screen.queryByRole("button", { name: /rules/i })).toBeNull();
+    expect(screen.queryByRole("button", { name: /channels/i })).toBeNull();
+    expect(rulesList).not.toHaveBeenCalled();
+  });
+});

client/src/components/__tests__/AlertsNotifications.spend.test.tsx

@@ -0,0 +1,102 @@
+/**
+ * @file Tests for the alert rule form's spend rules: a budget rule is built
+ * from period / limit / thresholds / AI tool (plus the browser's timezone
+ * offset), Preview shows what it would have fired without saving it, and
+ * Create saves the same config.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import userEvent from "@testing-library/user-event";
+
+vi.mock("../../lib/api", () => ({
+  api: {
+    alerts: {
+      list: vi.fn().mockResolvedValue({ alerts: [], total: 0, unacked: 0, limit: 50, offset: 0 }),
+      rules: {
+        list: vi.fn().mockResolvedValue({ rules: [] }),
+        create: vi.fn().mockResolvedValue({ rule: {} }),
+        preview: vi.fn().mockResolvedValue({
+          supported: true,
+          window_days: 7,
+          fires: 1,
+          sessions: 0,
+          samples: [],
+          periods: [
+            {
+              period_start: "2026-09-01",
+              period_end: "2026-09-30",
+              spend: 120,
+              pct: 120,
+              crossed: [80, 100],
+            },
+            {
+              period_start: "2026-10-01",
+              period_end: "2026-10-31",
+              spend: 10,
+              pct: 10,
+              crossed: [],
+            },
+          ],
+        }),
+      },
+    },
+    aiTools: {
+      list: vi.fn().mockResolvedValue({
+        tools: [{ id: "codex", label: "Codex" }],
+        default: "claude",
+      }),
+    },
+  },
+}));
+
+import { api } from "../../lib/api";
+import { AlertsNotifications } from "../AlertsNotifications";
+
+describe("AlertsNotifications — spend rules", () => {
+  it("previews and creates a budget rule", async () => {
+    const user = userEvent.setup();
+    render(
+      <MemoryRouter>
+        <AlertsNotifications />
+      </MemoryRouter>
+    );
+    await user.click(await screen.findByText("Add rule"));
+    await user.type(screen.getByPlaceholderText("e.g. Error burst"), "Monthly");
+    const selects = screen.getAllByRole("combobox");
+    await user.selectOptions(selects[0]!, "budget");
+    await user.selectOptions(screen.getByDisplayValue("month"), "week");
+    const limit = screen.getByDisplayValue("100");
+    await user.clear(limit);
+    await user.type(limit, "50");
+    await screen.findByRole("option", { name: "Codex" });
+    await user.selectOptions(screen.getByDisplayValue("All AI tools"), "codex");
+
+    await user.click(screen.getByRole("button", { name: /Preview/ }));
+    const config = {
+      period: "week",
+      limit_usd: 50,
+      thresholds: [80, 100],
+      tz_offset: new Date().getTimezoneOffset(),
+      tool: "codex",
+    };
+    expect(api.alerts.rules.preview).toHaveBeenCalledWith({
+      rule_type: "budget",
+      config,
+      cooldown_seconds: 300,
+    });
+    expect(await screen.findByText("2026-09-01")).toBeInTheDocument();
+    expect(screen.getByText("80% 100%")).toBeInTheDocument();
+    expect(api.alerts.rules.create).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole("button", { name: /Create rule/ }));
+    expect(api.alerts.rules.create).toHaveBeenCalledWith({
+      name: "Monthly",
+      rule_type: "budget",
+      config,
+      cooldown_seconds: 300,
+    });
+  });
+});

client/src/components/__tests__/AuthGate.test.tsx

@@ -0,0 +1,191 @@
+/**
+ * @file AuthGate.test.tsx
+ * @description The login gate: local mode renders the app untouched, server
+ * mode shows the login page until a login succeeds, a wrong password says so,
+ * and a later 401 `EAUTH` brings the login page back. `usePermissions` and
+ * `useWorkLanes` mirror the server's roles: an admin changes everything, an
+ * analyst reads everything but works only in their own workspaces, a
+ * developer only ever sees (and so changes) their own. The login page wears the
+ * OS's light/dark; a sign-in swaps in the account's saved appearance.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import "../../i18n";
+
+const me = vi.fn();
+const login = vi.fn();
+const prefs = vi.fn();
+const LANES = [
+  { id: 1, owner_id: 5 },
+  { id: 2, owner_id: 6 },
+];
+vi.mock("../../lib/api", () => ({
+  AUTH_REQUIRED_EVENT: "agenthub:auth-required",
+  api: {
+    auth: { me: () => me(), login: (u: string, p: string) => login(u, p), logout: vi.fn() },
+    lanes: { list: () => Promise.resolve({ lanes: LANES }) },
+    me: { prefs: () => prefs(), savePrefs: () => Promise.resolve({ prefs: {} }) },
+  },
+}));
+
+import { AuthGate, usePermissions } from "../AuthGate";
+import { useWorkLanes } from "../../hooks/useLanes";
+
+function Probe() {
+  const p = usePermissions();
+  const { lanes } = useWorkLanes();
+  return (
+    <p>
+      {[
+        `admin:${p.isAdmin}`,
+        `all:${p.seesAll}`,
+        `mine:${p.canEditLane({ owner_id: 5 })}`,
+        `theirs:${p.canEditLane({ owner_id: 6 })}`,
+        `work:${lanes.map((l) => l.id).join(",")}`,
+      ].join(" ")}
+    </p>
+  );
+}
+
+const user = { id: 1, username: "mia", role: "developer" };
+
+beforeEach(() => {
+  me.mockReset();
+  login.mockReset();
+  prefs.mockReset().mockResolvedValue({ prefs: {} });
+  localStorage.clear();
+});
+
+describe("AuthGate", () => {
+  it("renders the app in local mode", async () => {
+    me.mockResolvedValue({ mode: "local" });
+    render(<AuthGate>app</AuthGate>);
+    expect(await screen.findByText("app")).toBeInTheDocument();
+  });
+
+  it("paints at once in a browser that last saw local mode", () => {
+    localStorage.setItem("agenthub.authMode", "local");
+    me.mockReturnValue(new Promise(() => {}));
+    render(<AuthGate>app</AuthGate>);
+    expect(screen.getByText("app")).toBeInTheDocument();
+  });
+
+  it("asks again instead of guessing when the server does not answer", async () => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    try {
+      me.mockRejectedValueOnce(new Error("502"));
+      me.mockResolvedValue({ mode: "server", user: null });
+      render(<AuthGate>app</AuthGate>);
+      expect(screen.queryByText("app")).toBeNull();
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(2100);
+      });
+      expect(await screen.findByLabelText(/username/i)).toBeInTheDocument();
+      expect(screen.queryByText("app")).toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("renders the app when an older server or a dashboard token answers instead", async () => {
+    for (const err of [
+      { status: 404 },
+      { status: 200, code: "EBADRESPONSE" },
+      { status: 401, code: "EUNAUTHORIZED" },
+    ]) {
+      me.mockReset();
+      me.mockRejectedValue(Object.assign(new Error("x"), err));
+      const { unmount } = render(<AuthGate>app</AuthGate>);
+      expect(await screen.findByText("app")).toBeInTheDocument();
+      unmount();
+    }
+  });
+
+  it("asks for a login in server mode and opens the app after one", async () => {
+    me.mockResolvedValue({ mode: "server", user: null });
+    login.mockRejectedValueOnce(Object.assign(new Error("x"), { code: "EBADLOGIN" }));
+    login.mockResolvedValueOnce({ user });
+    render(<AuthGate>app</AuthGate>);
+
+    const name = await screen.findByLabelText(/username/i);
+    const pass = screen.getByLabelText(/^password$/i);
+    await userEvent.type(name, "mia");
+    await userEvent.type(pass, "nope");
+    await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
+    expect(await screen.findByRole("alert")).toBeInTheDocument();
+    expect(screen.queryByText("app")).toBeNull();
+
+    await userEvent.type(pass, "member-pass-1");
+    await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
+    expect(await screen.findByText("app")).toBeInTheDocument();
+    expect(login).toHaveBeenLastCalledWith("mia", "member-pass-1");
+
+    act(() => {
+      window.dispatchEvent(new Event("agenthub:auth-required"));
+    });
+    expect(await screen.findByLabelText(/username/i)).toBeInTheDocument();
+  });
+});
+
+describe("AuthGate theme", () => {
+  it("wears the OS theme while signed out and the account's own once signed in", async () => {
+    const html = document.documentElement;
+    // The previous user's choice, left in this browser.
+    localStorage.setItem("theme", "dark");
+    localStorage.setItem("agenthub.theme.dark", "darcula");
+    const mq = { matches: false, addEventListener: vi.fn(), removeEventListener: vi.fn() };
+    vi.stubGlobal("matchMedia", () => mq); // the OS is light
+    me.mockResolvedValue({ mode: "server", user: null });
+    prefs.mockResolvedValue({ prefs: { theme: "dark", "agenthub.theme.dark": "orca-dark" } });
+    login.mockResolvedValue({ user });
+    render(<AuthGate>app</AuthGate>);
+
+    await userEvent.type(await screen.findByLabelText(/username/i), "mia");
+    expect(html.dataset.mode).toBe("light");
+    expect(html.hasAttribute("data-theme")).toBe(false);
+
+    await userEvent.type(screen.getByLabelText(/^password$/i), "member-pass-1");
+    await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
+    await waitFor(() => expect(html.dataset.theme).toBe("orca-dark"));
+    expect(html.dataset.mode).toBe("dark");
+    expect(localStorage.getItem("agenthub.theme.dark")).toBe("orca-dark");
+    vi.unstubAllGlobals();
+  });
+});
+
+describe("usePermissions / useWorkLanes", () => {
+  const as = async (state: unknown) => {
+    cleanup();
+    me.mockResolvedValue(state);
+    render(
+      <AuthGate>
+        <Probe />
+      </AuthGate>
+    );
+    return (await screen.findByText(/work:\d/)).textContent;
+  };
+
+  it("lets an admin and local mode do everything", async () => {
+    for (const state of [
+      { mode: "local" },
+      { mode: "server", user: { id: 9, username: "boss", role: "admin" } },
+    ]) {
+      expect(await as(state)).toBe("admin:true all:true mine:true theirs:true work:1,2");
+    }
+  });
+
+  it("lets an analyst read everything but work only in their own workspaces", async () => {
+    expect(await as({ mode: "server", user: { id: 5, username: "ana", role: "analyst" } })).toBe(
+      "admin:false all:true mine:true theirs:false work:1"
+    );
+  });
+
+  it("lets a developer act on everything they can see, and nothing host-wide", async () => {
+    expect(await as({ mode: "server", user: { id: 5, username: "mia", role: "developer" } })).toBe(
+      "admin:false all:false mine:true theirs:true work:1,2"
+    );
+  });
+});

client/src/components/__tests__/EventReplay.test.tsx

@@ -0,0 +1,93 @@
+/**
+ * @file EventReplay.test.tsx
+ * @description The Replay tab's controls: step, jump, arrow keys, a lifecycle
+ * marker jumping the cursor, playback advancing on a timer, and the derived
+ * state following the cursor.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { EventReplay } from "../EventReplay";
+import type { DashboardEvent } from "../../lib/types";
+
+function ev(id: number, event_type: string, tool_name: string | null = null): DashboardEvent {
+  return {
+    id,
+    session_id: "s1",
+    agent_id: "a1",
+    event_type,
+    tool_name,
+    summary: `${event_type} ${tool_name ?? ""}`.trim(),
+    data: null,
+    created_at: new Date(Date.UTC(2026, 9, 1, 10, 0, id)).toISOString(),
+  } as DashboardEvent;
+}
+
+// Given newest first, as the events API answers: the replay orders them itself.
+const events = [
+  ev(4, "Stop"),
+  ev(3, "PostToolUse", "Bash"),
+  ev(2, "PreToolUse", "Bash"),
+  ev(1, "SessionStart"),
+];
+
+function renderReplay() {
+  return render(
+    <MemoryRouter>
+      <EventReplay events={events} agentInfoById={new Map()} sessionNameById={new Map()} />
+    </MemoryRouter>
+  );
+}
+
+const position = () => screen.getByText(/^\d+ \/ 4/);
+
+afterEach(() => vi.useRealTimers());
+
+describe("EventReplay", () => {
+  it("starts at the first event and steps with the buttons", () => {
+    renderReplay();
+    expect(position().textContent).toMatch(/^1 \/ 4/);
+    fireEvent.click(screen.getByTitle("Step forward (→)"));
+    fireEvent.click(screen.getByTitle("Step forward (→)"));
+    expect(position().textContent).toMatch(/^3 \/ 4/);
+    expect(screen.getByText("Bash ×1")).toBeTruthy();
+    fireEvent.click(screen.getByTitle("Jump to end (End)"));
+    expect(position().textContent).toMatch(/^4 \/ 4/);
+    fireEvent.click(screen.getByTitle("Jump to start (Home)"));
+    expect(position().textContent).toMatch(/^1 \/ 4/);
+  });
+
+  it("moves on arrow keys and jumps from a lifecycle marker", () => {
+    renderReplay();
+    const root = screen.getByTestId("event-replay");
+    fireEvent.keyDown(root, { key: "ArrowRight" });
+    expect(position().textContent).toMatch(/^2 \/ 4/);
+    // The in-flight tool at the PreToolUse.
+    expect(screen.getByText("Running tool").nextSibling?.textContent).toBe("Bash");
+    fireEvent.keyDown(root, { key: "End" });
+    expect(position().textContent).toMatch(/^4 \/ 4/);
+    fireEvent.click(screen.getByRole("button", { name: "Session start · #1" }));
+    expect(position().textContent).toMatch(/^1 \/ 4/);
+  });
+
+  it("plays to the end at the chosen speed", () => {
+    vi.useFakeTimers();
+    renderReplay();
+    fireEvent.click(screen.getByRole("button", { name: "5×" }));
+    fireEvent.click(screen.getByTitle("Play (Space)"));
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+    expect(position().textContent).toMatch(/^2 \/ 4/);
+    // One step per tick: each step schedules the next.
+    for (let i = 0; i < 3; i++) {
+      act(() => {
+        vi.advanceTimersByTime(100);
+      });
+    }
+    expect(position().textContent).toMatch(/^4 \/ 4/);
+    expect(screen.getByTitle("Play (Space)")).toBeTruthy();
+  });
+});

client/src/components/__tests__/Layout.test.tsx

@@ -3,7 +3,8 @@
  * @description Responsive shell: with no stored preference the sidebar starts
  * collapsed below `lg`, and below `md` it becomes an off-canvas drawer opened
  * from a menu button — a modal dialog that Escape and the backdrop close,
- * handing focus back to the button.
+ * handing focus back to the button. The expanded sidebar's edge resizes it
+ * within its bounds and remembers the width.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
@@ -16,7 +17,7 @@ vi.mock("../UpdateNotifier", () => ({ UpdateNotifier: () => null }));
 vi.mock("../StatusBar", () => ({ StatusBar: () => null }));
 vi.mock("../WorkspaceTree", () => ({ WorkspaceTree: () => null }));
 
-import { Layout, DRAWER_QUERY } from "../Layout";
+import { Layout, DRAWER_QUERY, SIDEBAR_MIN, SIDEBAR_MAX } from "../Layout";
 import { loadCollapsed, SIDEBAR_STORAGE_KEY } from "../Sidebar";
 
 function viewport(width: number) {
@@ -34,6 +35,7 @@ function viewport(width: number) {
 afterEach(() => {
   vi.unstubAllGlobals();
   localStorage.removeItem(SIDEBAR_STORAGE_KEY);
+  localStorage.removeItem("agenthub.sidebar.width");
 });
 
 describe("loadCollapsed", () => {
@@ -95,3 +97,47 @@ describe("Layout drawer", () => {
     expect(screen.getByRole("main").style.marginLeft).toBe("4.25rem");
   });
 });
+
+describe("Layout sidebar width", () => {
+  it("the edge drags within bounds, is remembered, and a double-click resets it", () => {
+    viewport(1440);
+    vi.stubGlobal("innerWidth", 2560);
+    render(
+      <MemoryRouter>
+        <Layout wsConnected />
+      </MemoryRouter>
+    );
+    const edge = screen.getByTestId("sidebar-resize");
+    const main = screen.getByRole("main");
+    expect(main.style.marginLeft).toBe(`${SIDEBAR_MIN}px`);
+
+    fireEvent.pointerDown(edge, { pointerId: 1 });
+    fireEvent.pointerMove(edge, { clientX: 360 });
+    fireEvent.pointerUp(edge, { clientX: 360 });
+    expect(main.style.marginLeft).toBe("360px");
+    expect(screen.getByTestId("sidebar").style.width).toBe("360px");
+    expect(localStorage.getItem("agenthub.sidebar.width")).toBe("360");
+
+    fireEvent.pointerDown(edge, { pointerId: 1 });
+    fireEvent.pointerUp(edge, { clientX: 2000 });
+    expect(main.style.marginLeft).toBe(`${SIDEBAR_MAX}px`);
+
+    fireEvent.keyDown(edge, { key: "ArrowLeft" });
+    expect(main.style.marginLeft).toBe(`${SIDEBAR_MAX - 16}px`);
+
+    fireEvent.doubleClick(edge);
+    expect(main.style.marginLeft).toBe(`${SIDEBAR_MIN}px`);
+  });
+
+  it("never wider than 40% of the window", () => {
+    viewport(1100);
+    vi.stubGlobal("innerWidth", 1100);
+    localStorage.setItem("agenthub.sidebar.width", "480");
+    render(
+      <MemoryRouter>
+        <Layout wsConnected />
+      </MemoryRouter>
+    );
+    expect(screen.getByRole("main").style.marginLeft).toBe("440px");
+  });
+});

client/src/components/__tests__/Select.test.tsx

@@ -2,7 +2,8 @@
  * @file Select.test.tsx
  * @description The shared Select as a WAI-ARIA listbox button: expanded state,
  * listbox/option roles with aria-selected, aria-activedescendant tracking,
- * Arrow/Home/End/Enter/Escape/type-ahead, and focus back on the trigger.
+ * Arrow/Home/End/Enter/Escape/type-ahead, focus back on the trigger, and a
+ * list that flips up by the room in its split pane, not the window's.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
@@ -90,4 +91,21 @@ describe("Select (listbox button)", () => {
     fireEvent.click(screen.getByText("Apple"));
     expect(onChange).toHaveBeenCalledWith("a");
   });
+
+  it("opens upward when its pane (data-menu-bounds) has no room below, whatever the window has", () => {
+    const rect = (top: number, bottom: number) => ({ top, bottom }) as DOMRect;
+    render(
+      <div data-menu-bounds data-testid="pane">
+        <Select value="b" onChange={() => {}} options={OPTIONS} label="Fruit" />
+      </div>
+    );
+    // A top pane 0–400 in a 2000px window; the trigger near its bottom.
+    vi.spyOn(screen.getByTestId("pane"), "getBoundingClientRect").mockReturnValue(rect(0, 400));
+    const button = screen.getByRole("button", { name: "Fruit" });
+    vi.spyOn(button, "getBoundingClientRect").mockReturnValue(rect(360, 380));
+    vi.stubGlobal("innerHeight", 2000);
+    fireEvent.click(button);
+    expect(screen.getByRole("listbox").className).toContain("bottom-full");
+    vi.unstubAllGlobals();
+  });
 });

client/src/components/__tests__/StatusBar.test.tsx

@@ -24,6 +24,7 @@ function today() {
 
 vi.mock("../../lib/api", () => ({
   api: {
+    aiTools: { iconUrl: (id: string) => `/api/ai-tools/${id}/icon` },
     sessions: {
       // 3 active sessions, 1 of them waiting on the user.
       list: vi.fn().mockImplementation(async (p: { awaiting?: boolean }) => ({
@@ -76,6 +77,7 @@ vi.mock("../../lib/api", () => ({
             active: true,
             label: "Work",
             account: "me@example.com",
+            plan: "max",
             expiresAt: new Date(Date.now() + 3 * 3600_000 + 30_000).toISOString(),
             windows: [
               {
@@ -102,6 +104,22 @@ vi.mock("../../lib/api", () => ({
             windows: [],
             error: "EUPSTREAM",
           },
+          {
+            id: "antigravity",
+            active: true,
+            windows: [
+              { group: "Gemini Models", label: "5h", usedPercent: 0, resetsAt: null },
+              { group: "Gemini Models", label: "wk", usedPercent: 25, resetsAt: null },
+              { group: "Claude and GPT models", label: "5h", usedPercent: 50, resetsAt: null },
+            ],
+          },
+          {
+            id: "cursor",
+            active: true,
+            account: "c@example.com",
+            plan: "pro",
+            windows: [{ label: "mo", usedPercent: 40, resetsAt: null }],
+          },
         ],
         checkedAt: "",
       }),
@@ -111,6 +129,21 @@ vi.mock("../../lib/api", () => ({
         daily_costs: [],
       })),
     },
+    budgets: {
+      status: vi.fn().mockResolvedValue({
+        budgets: [
+          { id: "b1", name: "Quiet", config: { limit_usd: 100 }, spend: 10, pct: 10, crossed: [] },
+          {
+            id: "b2",
+            name: "Monthly",
+            config: { limit_usd: 100 },
+            spend: 85,
+            pct: 85,
+            crossed: [80],
+          },
+        ],
+      }),
+    },
   },
 }));
 
@@ -142,6 +175,14 @@ describe("StatusBar", () => {
     expect(screen.getByRole("status")).toHaveTextContent("Live · 1 need you");
   });
 
+  it("flags the budget furthest past a threshold, linking to the cost analytics", async () => {
+    at("/", <StatusBar wsConnected left="0" onConnectionClick={() => {}} />);
+    const chip = await screen.findByTestId("status-bar-budget");
+    expect(chip.textContent).toBe("Budget 85%");
+    expect(chip.getAttribute("href")).toBe("/?tab=analytics&sub=cost");
+    expect(chip.getAttribute("title")).toBe("Monthly: $85.00 of $100.00 this period");
+  });
+
   it("says Disconnected when the socket is down", () => {
     at("/", <StatusBar wsConnected={false} left="0" onConnectionClick={() => {}} />);
     expect(screen.getByRole("button", { name: /Disconnected/ })).toBeInTheDocument();
@@ -191,10 +232,10 @@ describe("StatusBar", () => {
     expect(screen.getByText("95% used")).toHaveClass("text-status-danger");
     await user.hover(chips);
     const panel = screen.getByTestId("status-bar-quota-panel");
-    const [work, personal, codex] = screen.getAllByTestId("status-bar-quota-account");
-    expect(work).toHaveTextContent("Workin use");
+    const [work, personal, codex, agy, cursor] = screen.getAllByTestId("status-bar-quota-account");
+    expect(work).toHaveTextContent("Workmaxin use");
     expect(work).toHaveTextContent("me@example.com · Sign-in expires in 3h 0m");
-    expect(work).toHaveTextContent("5h95%41m");
+    expect(work).toHaveTextContent("5h95%Resets in 41m");
     expect(work).toHaveTextContent("Week32%");
     expect(personal).toHaveTextContent("home@example.com · Sign-in expired");
     expect(personal).toHaveTextContent("Check quota in Claude Code → Profiles");
@@ -202,6 +243,11 @@ describe("StatusBar", () => {
     expect(codex).toHaveTextContent("dev@example.com");
     expect(codex).toHaveTextContent("Sign-in expired");
     expect(panel).toHaveTextContent("Could not read the quota");
+    expect(agy).toHaveTextContent("Gemini Models5h0%Week25%Claude and GPT models5h50%");
+    expect(chips).toHaveTextContent("Antigravity50% used");
+    expect(cursor).toHaveTextContent("c@example.compro");
+    expect(cursor).toHaveTextContent("Month40%");
+    expect(chips).toHaveTextContent("Cursor40% used");
     // Moving onto the panel keeps it open, so it can be read; leaving it closes it.
     await user.unhover(chips);
     await user.hover(panel);
@@ -221,7 +267,11 @@ describe("StatusBar", () => {
     await user.click(refresh);
     expect(api.pricing.quota).toHaveBeenCalledTimes(1);
     await act(async () => answer(same));
-    expect(screen.getByTestId("status-bar-quota-refresh")).toHaveTextContent("Refresh");
+    // The spin outlasts an instant answer (a throttled refresh is served from
+    // cache), so the label returns after the minimum spin.
+    await waitFor(() =>
+      expect(screen.getByTestId("status-bar-quota-refresh")).toHaveTextContent(/^Refresh$/)
+    );
     expect(screen.getByTestId("status-bar-quota-panel")).toBeInTheDocument();
     await user.unhover(panel);
     await waitFor(() => expect(screen.queryByTestId("status-bar-quota-panel")).toBeNull());

client/src/components/__tests__/UpdateNotifier.test.tsx

@@ -222,6 +222,40 @@ describe("UpdateNotifier — Update now", () => {
   });
 });
 
+describe("UpdateNotifier — plugin chain verdict", () => {
+  it("stops Restarting when the chain fails and the old server stays up", async () => {
+    const PLUGIN: UpdateStatusPayload = {
+      ...BASE_STATUS,
+      situation: "plugin_managed",
+      install_kind: "plugin",
+      plugin_marketplace: "sg",
+      plugin_name: "agenthub",
+      commits_behind: 0,
+      local_version: "1.5.0",
+      release_check: "ok",
+      latest_release: "v1.6.0",
+    };
+    statusMock.mockResolvedValue(PLUGIN);
+    applyMock.mockResolvedValue({ ...PLUGIN, applied: true, mode: "plugin" });
+    render(<UpdateNotifier />);
+    await userEvent.click(await screen.findByText(i18n.t("updates:updateNow")));
+    await screen.findAllByText(i18n.t("updates:pluginUpdating"));
+
+    // The old server answers again, now carrying this chain's failed verdict.
+    statusMock.mockResolvedValue({
+      ...PLUGIN,
+      last_plugin_update: {
+        ok: false,
+        step: "plugin_update",
+        error: "boom",
+        finished_at: new Date().toISOString(),
+      },
+    });
+    expect(await screen.findByText(/plugin_update/, {}, { timeout: 4000 })).toBeInTheDocument();
+    expect(screen.queryByText(i18n.t("updates:pluginUpdating"))).not.toBeInTheDocument();
+  });
+});
+
 describe("UpdateNotifier — closing vs skipping", () => {
   it("Escape only closes for now; Skip this version is the persistent dismiss", async () => {
     const { unmount } = render(<UpdateNotifier />);

client/src/components/__tests__/WorkspaceTree.owners.test.tsx

@@ -0,0 +1,143 @@
+/**
+ * @file WorkspaceTree.owners.test.tsx
+ * @description Server mode, the sidebar workspace list for an analyst: every
+ * user's workspaces, grouped under their owner (yours first, no owner last),
+ * groups folding and remembered; another user's workspace is read only — no
+ * menu, no new session, and a session opens its analysis page, never a pane.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter, Route, Routes, useLocation } from "react-router-dom";
+import type { Lane, Session } from "../../lib/types";
+
+const ME = { id: 2, username: "ana", role: "analyst" as const };
+
+const lane = (id: number, owner: number | null, name: string | null, title: string) =>
+  ({
+    id,
+    title,
+    cwd: `/w/${id}`,
+    kind: "adopted",
+    tool: "claude",
+    status: "idle",
+    liveness: "idle",
+    pipeline_nodes: [],
+    owner_id: owner,
+    owner_name: name,
+  }) as unknown as Lane;
+
+const lanes = [
+  lane(1, 3, "bob", "Bob app"),
+  lane(2, null, null, "Old"),
+  lane(3, ME.id, "ana", "Mine"),
+  lane(4, 1, "admin", "Admin site"),
+];
+
+vi.mock("../AuthGate", () => ({
+  useAuth: () => ({ state: { mode: "server", user: ME } }),
+  usePermissions: () => ({
+    isAdmin: false,
+    seesAll: true,
+    canEditLane: (l?: { owner_id?: number | null } | null) => l?.owner_id === ME.id,
+  }),
+}));
+vi.mock("../../lib/api", async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    api: {
+      lanes: { list: vi.fn(async () => ({ lanes, counts: {} })) },
+      sessions: {
+        list: vi.fn(async () => ({
+          sessions: [
+            { id: "s-1", name: "Bob's run", status: "completed", started_at: "2026-10-01" },
+          ] as Session[],
+          total: 1,
+          limit: 6,
+          offset: 0,
+        })),
+      },
+      run: { list: vi.fn(async () => ({ items: [] })) },
+      aiTools: { list: vi.fn(async () => ({ tools: [], default: "claude" })), iconUrl: () => "" },
+    },
+  };
+});
+
+import { WorkspaceTree } from "../WorkspaceTree";
+
+function Where() {
+  const loc = useLocation();
+  return <span data-testid="where">{loc.pathname + loc.search}</span>;
+}
+
+function renderTree() {
+  return render(
+    <MemoryRouter>
+      <Routes>
+        <Route
+          path="*"
+          element={
+            <>
+              <WorkspaceTree />
+              <Where />
+            </>
+          }
+        />
+      </Routes>
+    </MemoryRouter>
+  );
+}
+
+beforeEach(() => localStorage.clear());
+
+describe("WorkspaceTree for an analyst", () => {
+  it("groups every workspace under its owner: yours first, no owner last", async () => {
+    renderTree();
+    await screen.findByTestId("workspace-row-1");
+    const order = screen
+      .getAllByTestId(/^workspace-(owner-\w+|row-\d+)$/)
+      .map((el) => el.dataset.testid);
+    expect(order).toEqual([
+      "workspace-owner-2",
+      "workspace-row-3",
+      "workspace-owner-1",
+      "workspace-row-4",
+      "workspace-owner-3",
+      "workspace-row-1",
+      "workspace-owner-none",
+      "workspace-row-2",
+    ]);
+    expect(screen.getByTestId("workspace-owner-2")).toHaveTextContent("ana (you)");
+  });
+
+  it("folds a group and remembers it", async () => {
+    const user = userEvent.setup();
+    renderTree();
+    await user.click(await screen.findByTestId("workspace-owner-3"));
+    expect(screen.queryByTestId("workspace-row-1")).toBeNull();
+    expect(screen.getByTestId("workspace-owner-3")).toHaveAttribute("aria-expanded", "false");
+    expect(JSON.parse(localStorage.getItem("agenthub.sidebar.projects")!).collapsedOwners).toEqual({
+      "3": true,
+    });
+  });
+
+  it("keeps another user's workspace read only", async () => {
+    const user = userEvent.setup();
+    renderTree();
+    await screen.findByTestId("workspace-row-1");
+    // Yours keeps its controls; theirs has none.
+    expect(screen.getByTestId("workspace-menu-3")).toBeInTheDocument();
+    expect(screen.queryByTestId("workspace-menu-1")).toBeNull();
+    expect(screen.queryByTestId("workspace-new-1")).toBeNull();
+    // Picking it unfolds it instead of opening a workspace home.
+    await user.click(screen.getByTestId("workspace-open-1"));
+    expect(screen.getByTestId("where")).toHaveTextContent(/^\/$/);
+    const list = await screen.findByTestId("workspace-sessions-1");
+    expect(within(list).queryByTestId("workspace-session-archive-s-1")).toBeNull();
+    await user.click(within(list).getByTestId("workspace-session-s-1"));
+    expect(screen.getByTestId("where")).toHaveTextContent("/sessions/s-1");
+  });
+});

client/src/components/__tests__/WorkspaceTree.test.tsx

@@ -81,14 +81,12 @@ vi.mock("../../lib/api", async (importOriginal) => {
         })),
         cwds: vi.fn(async () => ({ items: [] })),
         kill: vi.fn(async () => ({ ok: true })),
-        history: vi.fn(async () => ({ items: [] })),
-        forgetHistory: vi.fn(async () => ({ removed: "" })),
       },
       aiTools: {
         list: vi.fn(async () => ({ tools: [], default: "claude" })),
         iconUrl: () => "",
       },
-      aiRouters: { list: vi.fn(async () => ({ routers: [] })) },
+      aiProxies: { list: vi.fn(async () => ({ items: [] })) },
     },
   };
 });
@@ -180,6 +178,10 @@ describe("WorkspaceTree", () => {
     expect(api.sessions.list).toHaveBeenLastCalledWith({ lane: 1, archived: false, limit: 9 });
     await screen.findByText("Session 8");
     expect(screen.queryByTestId("workspace-sessions-more-1")).toBeNull();
+    await user.click(screen.getByTestId("workspace-sessions-less-1"));
+    expect(api.sessions.list).toHaveBeenLastCalledWith({ lane: 1, archived: false, limit: 6 });
+    expect(await screen.findByTestId("workspace-sessions-more-1")).toBeInTheDocument();
+    expect(screen.queryByTestId("workspace-sessions-less-1")).toBeNull();
   });
 
   it("renames a session on double-click + Enter, and archives one from its row", async () => {
@@ -309,6 +311,23 @@ describe("WorkspaceTree", () => {
     expect(api.lanes.action).not.toHaveBeenCalled();
   });
 
+  it("lists live sessions above ended ones, even an ended one active more recently", async () => {
+    vi.mocked(api.sessions.list).mockImplementation(async () => ({
+      sessions: [session("s-old", "Old one"), session("s-live", "Live one")],
+      total: 2,
+      limit: 20,
+      offset: 0,
+    }));
+    const user = userEvent.setup();
+    renderTree();
+    await user.click(await screen.findByTestId("workspace-toggle-1"));
+    await waitFor(() =>
+      expect(screen.getByTestId("workspace-session-s-live")).toHaveAttribute("data-live", "true")
+    );
+    const ids = screen.getAllByTestId(/^workspace-session-s-/).map((el) => el.dataset.testid);
+    expect(ids).toEqual(["workspace-session-s-live", "workspace-session-s-old"]);
+  });
+
   it("shows a live tab whose session has no row yet as a New session, and a shell as Terminal", async () => {
     vi.mocked(api.run.list).mockImplementation(
       async () =>
@@ -351,97 +370,6 @@ describe("WorkspaceTree", () => {
     expect(screen.getByTestId("where").textContent).toBe("/workspace?lane=1&run=agenthub-lane-1");
   });
 
-  it("lists a workspace's closed terminals, and a click opens a new shell tab", async () => {
-    vi.mocked(api.run.history).mockImplementation(
-      async () =>
-        ({
-          items: [
-            {
-              id: "agenthub-lane-1-2",
-              tool: "shell",
-              status: "running",
-              started_at: "2026-10-06T10:00:00Z",
-              ended_at: null,
-              isLive: true,
-            },
-            {
-              id: "agenthub-lane-1-3@a",
-              tool: "shell",
-              status: "killed",
-              started_at: "2026-10-06T09:00:00Z",
-              ended_at: "2026-10-06T09:05:00Z",
-              isLive: false,
-            },
-            {
-              id: "agenthub-lane-1-1@b",
-              tool: "shell",
-              status: "exited",
-              started_at: "2026-10-06T08:00:00Z",
-              ended_at: "2026-10-06T08:05:00Z",
-              isLive: false,
-            },
-            {
-              id: "agenthub-lane-1-1@c",
-              tool: "shell",
-              status: "exited",
-              started_at: "2026-10-06T07:00:00Z",
-              ended_at: "2026-10-06T07:05:00Z",
-              isLive: false,
-            },
-            {
-              id: "agenthub-lane-1-1@d",
-              tool: "shell",
-              status: "exited",
-              started_at: "2026-10-06T06:00:00Z",
-              ended_at: "2026-10-06T06:05:00Z",
-              isLive: false,
-            },
-          ],
-        }) as never
-    );
-    vi.mocked(api.lanes.action).mockImplementation(
-      async () => ({ ok: true, run_id: "agenthub-lane-1-3" }) as never
-    );
-    const user = userEvent.setup();
-    renderTree();
-    await user.click(await screen.findByTestId("workspace-toggle-1"));
-    const closed = await screen.findByTestId("workspace-terminal-closed-agenthub-lane-1-3@a");
-    expect(closed).toHaveTextContent("Terminal");
-    expect(api.run.history).toHaveBeenCalledWith(
-      expect.objectContaining({ laneId: 1, tool: "shell" })
-    );
-    // The live one is not history, and only the newest three are listed.
-    expect(screen.queryByTestId("workspace-terminal-closed-agenthub-lane-1-2")).toBeNull();
-    expect(screen.getAllByTestId(/^workspace-terminal-closed-/)).toHaveLength(3);
-    await user.click(closed);
-    expect(api.lanes.action).toHaveBeenCalledWith(1, "start", { shell: true, slot: "auto" });
-    expect(screen.getByTestId("where").textContent).toBe("/workspace?lane=1&run=agenthub-lane-1-3");
-  });
-
-  it("removes a closed terminal from its hover X and its right-click menu", async () => {
-    const shell = (id: string) => ({
-      id,
-      tool: "shell",
-      status: "exited",
-      started_at: "2026-10-06T08:00:00Z",
-      ended_at: "2026-10-06T08:05:00Z",
-      isLive: false,
-    });
-    vi.mocked(api.run.history).mockImplementation(
-      async () => ({ items: [shell("t-a"), shell("t-b")] }) as never
-    );
-    const user = userEvent.setup();
-    renderTree();
-    await user.click(await screen.findByTestId("workspace-toggle-1"));
-    await user.click(await screen.findByTestId("workspace-terminal-forget-t-a"));
-    expect(api.run.forgetHistory).toHaveBeenCalledWith("t-a");
-    await waitFor(() => expect(screen.queryByTestId("workspace-terminal-closed-t-a")).toBeNull());
-    fireEvent.contextMenu(screen.getByTestId("workspace-terminal-closed-t-b"));
-    await user.click(screen.getByText("Remove from list"));
-    expect(api.run.forgetHistory).toHaveBeenCalledWith("t-b");
-    await waitFor(() => expect(screen.queryByTestId("workspace-terminal-closed-t-b")).toBeNull());
-  });
-
   it("selects by URL, and a click selects and expands", async () => {
     const user = userEvent.setup();
     renderTree("/workspace?lane=2");

client/src/components/config/ConfirmDeleteModal.tsx

@@ -67,7 +67,7 @@ export function ConfirmDeleteModal<
         aria-modal="true"
         aria-labelledby="cc-confirm-delete-title"
         aria-describedby="cc-confirm-delete-body"
-        className="relative w-full max-w-lg rounded-xl border border-status-danger/40 bg-surface-1"
+        className="relative flex max-h-full w-full max-w-lg flex-col rounded-xl border border-status-danger/40 bg-surface-1"
         onClick={(e) => e.stopPropagation()}
       >
         <div className="border-b border-border px-4 py-2.5 flex items-center gap-2">
@@ -76,7 +76,7 @@ export function ConfirmDeleteModal<
             {t("edit.confirmDelete")}
           </span>
         </div>
-        <div className="p-4 space-y-3">
+        <div className="min-h-0 overflow-y-auto p-4 space-y-3">
           <p id="cc-confirm-delete-body" className="text-xs text-fg-secondary leading-relaxed">
             {t("edit.confirmDeleteBody")}
           </p>

client/src/components/conversation/ConversationView.tsx

@@ -5,7 +5,11 @@
  * the message stream via MessageList. Combines a WebSocket subscription, a
  * visibility-gated polling fallback, and a manual refresh button so the view
  * stays caught up even when hooks miss frames or the user is mid-text-only
- * turn (no PreToolUse fires until Stop).
+ * turn (no PreToolUse fires until Stop). The view sticks to its end while
+ * the reader is there: anything that makes it taller — a new line, the live
+ * step, an image loading, the pane shown again after being hidden by CSS
+ * (a `display:none` pane cannot scroll) — keeps the newest in sight, until the
+ * reader scrolls up; `follow` (a chat's send) sends it back to the end.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 /* =============================================================================
@@ -59,6 +63,7 @@ import { api } from "../../lib/api";
 import { eventBus } from "../../lib/eventBus";
 import { isRemoteDataRefreshMessage } from "../../lib/remoteDataEvents";
 import { MessageList } from "./MessageList";
+import { useSpin } from "../../hooks/useSpin";
 import { useTranslation } from "react-i18next";
 import type { TranscriptMessage, TranscriptInfo, WSMessage } from "../../lib/types";
 
@@ -75,9 +80,25 @@ const TRANSCRIPTS_REFRESH_MS = 15000;
 interface ConversationViewProps {
   sessionId: string;
   initialTranscriptId?: string | null;
+  /** Fill the parent as a chat (a workspace's session view): no toolbar, no
+   *  page-height cap — the parent sizes it and puts a composer under it. */
+  fill?: boolean;
+  /** Opens a file named in a turn's "Edited N files" card. */
+  onOpenFile?: (path: string) => void;
+  /** The session runs in a pane: show the step in progress. */
+  live?: boolean;
+  /** Changed (a chat's send): back to the end, and stick to it. */
+  follow?: number;
 }
 
-export function ConversationView({ sessionId, initialTranscriptId }: ConversationViewProps) {
+export function ConversationView({
+  sessionId,
+  initialTranscriptId,
+  fill = false,
+  onOpenFile,
+  live = false,
+  follow = 0,
+}: ConversationViewProps) {
   const { t } = useTranslation("sessions");
   const [messages, setMessages] = useState<TranscriptMessage[]>([]);
   const [total, setTotal] = useState(0);
@@ -90,11 +111,14 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
   const [error, setError] = useState<string | null>(null);
   const [transcripts, setTranscripts] = useState<TranscriptInfo[]>([]);
   const [showNewMsg, setShowNewMsg] = useState(false);
+  // Scrolled up from the end: a chat (`fill`) offers the way back down.
+  const [awayFromEnd, setAwayFromEnd] = useState(false);
 
   // Track JSONL line numbers for incremental requests and history loading
   const lastLineRef = useRef(0);
   const firstLineRef = useRef(0);
   const scrollContainerRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
   const isAtBottomRef = useRef(true);
   const fetchingRef = useRef(false);
   // When a fetch is in flight and a new trigger arrives (WS event, poll,
@@ -106,7 +130,6 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
   const genRef = useRef(0);
   // Refresh-button spinner state - separate from initial `loading` so the
   // existing skeleton doesn't blink during a manual refresh.
-  const [refreshing, setRefreshing] = useState(false);
 
   // Load available transcript list (also rescanned on a short interval so
   // newly-spawned subagents appear in the dropdown without a page reload).
@@ -162,7 +185,10 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
         firstLineRef.current = result.first_line;
       } catch (err) {
         if (cancelled) return;
-        setError(err instanceof Error ? err.message : t("conversation.failedLoad"));
+        // A live pane's new session has no row until its first hook: nothing
+        // to show yet, and the poll below picks it up once it exists.
+        const notYet = live && (err as { code?: string }).code === "NOT_FOUND";
+        if (!notYet) setError(err instanceof Error ? err.message : t("conversation.failedLoad"));
         setMessages([]);
         setTotal(0);
       } finally {
@@ -242,6 +268,8 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
   // also poll below to catch what WS misses.
   useEffect(() => {
     const unsubscribe = eventBus.subscribe((msg: WSMessage) => {
+      // Hidden tab: the visibility handler below catches up once on show.
+      if (document.visibilityState !== "visible") return;
       if (isRemoteDataRefreshMessage(msg)) {
         fetchNewMessages();
         return;
@@ -303,14 +331,7 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
 
   // Manual refresh - surfaces a control in the toolbar so users can force
   // a sync without reloading the page.
-  const refresh = useCallback(async () => {
-    setRefreshing(true);
-    try {
-      await fetchNewMessages();
-    } finally {
-      setRefreshing(false);
-    }
-  }, [fetchNewMessages]);
+  const [refreshing, refresh] = useSpin(fetchNewMessages);
 
   // Scroll-up to load history
   const loadHistory = useCallback(async () => {
@@ -375,6 +396,7 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
     // Detect if at bottom
     const atBottom = container.scrollHeight - container.scrollTop - container.clientHeight < 100;
     isAtBottomRef.current = atBottom;
+    setAwayFromEnd(!atBottom);
 
     // Hide "new messages" indicator when scrolled to bottom
     if (atBottom) {
@@ -387,6 +409,30 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
     }
   }, [hasMore, loadingHistory, loadHistory]);
 
+  // Stick to the end while the reader is there. Scroll events say whether
+  // they are; a size change — of the content, or of the box itself when a
+  // hidden pane is shown — never fires one, so it is watched here.
+  useEffect(() => {
+    const container = scrollContainerRef.current;
+    const content = contentRef.current;
+    if (!container || !content || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      if (isAtBottomRef.current) container.scrollTop = container.scrollHeight;
+    });
+    observer.observe(container);
+    observer.observe(content);
+    return () => observer.disconnect();
+  }, []);
+
+  // The reader sent a message: show it, and what follows, as it lands.
+  useEffect(() => {
+    if (!follow) return;
+    isAtBottomRef.current = true;
+    setAwayFromEnd(false);
+    setShowNewMsg(false);
+    scrollToBottom();
+  }, [follow, scrollToBottom]);
+
   // Auto-scroll to bottom after initial load
   useEffect(() => {
     if (!loading && messages.length > 0) {
@@ -395,10 +441,10 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
   }, [loading, scrollToBottom]); // eslint-disable-line react-hooks/exhaustive-deps
 
   return (
-    <div className="relative flex flex-col" style={{ minHeight: 0 }}>
+    <div className={`relative flex flex-col ${fill ? "h-full" : ""}`} style={{ minHeight: 0 }}>
       {/* Toolbar - always rendered after the initial load so users can
           refresh even when no messages have streamed yet. */}
-      {!loading && (
+      {!loading && !fill && (
         <div className="flex items-center gap-3 mb-3 flex-shrink-0">
           {transcripts.length > 1 && (
             <div className="relative">
@@ -445,42 +491,66 @@ export function ConversationView({ sessionId, initialTranscriptId }: Conversatio
       <div
         ref={scrollContainerRef}
         onScroll={handleScroll}
-        className="flex-1 overflow-y-auto"
-        style={{ maxHeight: "calc(100vh - 320px)", minHeight: 200 }}
+        className="flex-1 overflow-y-auto [scrollbar-gutter:stable]"
+        style={fill ? { minHeight: 0 } : { maxHeight: "calc(100vh - 320px)", minHeight: 200 }}
       >
-        {/* History loading indicator */}
-        {loadingHistory && (
-          <div className="flex justify-center py-3">
-            <Loader2 className="w-4 h-4 text-fg-muted animate-spin" />
-            <span className="text-xs text-fg-muted ml-2">{t("conversation.loadingHistory")}</span>
-          </div>
-        )}
+        <div ref={contentRef}>
+          {/* History loading indicator */}
+          {loadingHistory && (
+            <div className="flex justify-center py-3">
+              <Loader2 className="w-4 h-4 text-fg-muted animate-spin" />
+              <span className="text-xs text-fg-muted ml-2">{t("conversation.loadingHistory")}</span>
+            </div>
+          )}
 
-        {/* Scroll-up for history hint */}
-        {hasMore && !loadingHistory && !loading && (
-          <div className="flex justify-center py-2">
-            <span className="text-[11px] text-fg-muted">↑ {t("conversation.scrollForOlder")}</span>
-          </div>
-        )}
+          {/* Scroll-up for history hint */}
+          {hasMore && !loadingHistory && !loading && (
+            <div className="flex justify-center py-2">
+              <span className="text-[11px] text-fg-muted">
+                ↑ {t("conversation.scrollForOlder")}
+              </span>
+            </div>
+          )}
 
-        {loading ? (
-          <div className="flex items-center justify-center py-12 text-fg-muted text-sm">
-            {t("conversation.loading")}
-          </div>
-        ) : messages.length === 0 ? (
-          <div className="mx-auto max-w-md py-12 text-center">
-            <p className="text-sm text-fg-secondary">{t("conversation.empty")}</p>
-            <p className="mt-2 text-xs leading-relaxed text-fg-muted">
-              {t("conversation.emptyBody")}
-            </p>
-          </div>
-        ) : (
-          <MessageList messages={messages} loading={false} />
-        )}
+          {loading ? (
+            <div className="flex items-center justify-center py-12 text-fg-muted text-sm">
+              {t("conversation.loading")}
+            </div>
+          ) : messages.length === 0 ? (
+            <div className="mx-auto max-w-md py-12 text-center">
+              <p className="text-sm text-fg-secondary">{t("conversation.empty")}</p>
+              <p className="mt-2 text-xs leading-relaxed text-fg-muted">
+                {t("conversation.emptyBody")}
+              </p>
+            </div>
+          ) : (
+            <MessageList messages={messages} loading={false} onOpenFile={onOpenFile} live={live} />
+          )}
+        </div>
       </div>
 
+      {/* Claude Desktop's round "back to the end" button */}
+      {fill && awayFromEnd && (
+        <button
+          type="button"
+          data-testid="conversation-to-end"
+          onClick={() => {
+            scrollToBottom();
+            setShowNewMsg(false);
+          }}
+          aria-label={t("conversation.newMessages")}
+          title={t("conversation.newMessages")}
+          className="absolute bottom-3 left-1/2 z-10 flex h-8 w-8 -translate-x-1/2 items-center justify-center rounded-full border border-border bg-surface-1 text-fg-secondary shadow-md transition-colors hover:text-fg-primary"
+        >
+          <ArrowDown className="h-4 w-4" />
+          {showNewMsg && (
+            <span className="absolute right-0 top-0 h-2 w-2 rounded-full bg-accent-solid" />
+          )}
+        </button>
+      )}
+
       {/* New messages indicator */}
-      {showNewMsg && (
+      {showNewMsg && !fill && (
         <button
           onClick={() => {
             scrollToBottom();

client/src/components/conversation/MarkdownContent.tsx

@@ -4,7 +4,12 @@
  * subset of CommonMark + GFM that actually appears in Claude Code transcripts:
  * fenced code blocks, ATX headings, ordered/unordered lists, task lists, blockquotes,
  * horizontal rules, simple tables, inline code, bold, italic, strikethrough, links,
- * and auto-linked URLs.
+ * and auto-linked URLs. An absolute file path (bare or in inline code) opens
+ * through `OpenFileContext` when the page provides one; `linkify` does the
+ * same links for plain text. To make a reply easy to scan, bold is coloured
+ * (accent), standalone numbers (87%, 3.5s, v2.7.1, dates) are tinted and
+ * tabular, and a flag label ("Lưu ý:", "Warning:", "Lỗi:") takes the colour
+ * of how serious it is.
  *
  * Output is built as a React element tree (no dangerouslySetInnerHTML) so user content
  * is escaped by React. Code blocks delegate to <CodeBlock /> for syntax highlighting and
@@ -244,6 +249,87 @@ function parseBlocks(src: string): Block[] {
   return blocks;
 }
 
+/** Opens a file a message names; provided by a view that can show one. */
+export const OpenFileContext = React.createContext<((path: string) => void) | undefined>(undefined);
+
+const LINK_CLASS =
+  "text-violet-700 dark:text-violet-300 hover:text-violet-800 dark:hover:text-violet-200 underline underline-offset-2 decoration-violet-400/40 hover:decoration-violet-300/70 break-all";
+const URL_RE = /^https?:\/\/[^\s<>()]+[^\s<>().,!?;:'"]/;
+// Two segments at least, so "/" or "/s" stays text; a trailing full stop is prose.
+const PATH_RE = /^(?:\/[^\s/<>()'"`,;:]*[^\s/<>()'"`,;:.!?]){2,}/;
+// A link starts a word: "and/or" or "a/b/c" stays text.
+const atWordStart = (text: string, i: number) => i === 0 || /[\s([{"'`]/.test(text[i - 1]!);
+// A number worth spotting: 42, 1,234.5, 87%, $1.20, 3.5s, 12MB, v2.7.1, 2026-10-12, 12:30,
+// 2026-10-12T08:00:00Z. It must stand alone, so "abc123", "file.2", "#67" and a sha like
+// "2fd0c903" stay text.
+const NUM_RE =
+  /^(?:[-+−]?[$€£¥]?|v)\d+(?:[.,:/-]\d+)*(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?(?:%|×|x|k|K|M|B|KB|MB|GB|TB|ms|s|m|h|d|px|đ)?(?![\p{L}\p{N}_])/u;
+const numStart = (text: string, i: number) =>
+  i === 0 || !/[\p{L}\p{N}_.\/\\#@-]/u.test(text[i - 1]!);
+// A label that flags what follows — "Lưu ý:", "Warning:" — coloured by how serious it is.
+const LABEL_RE =
+  /^(Error|Lỗi|Caution|Danger|Breaking|Warning|Cảnh báo|Important|Quan trọng|Chú ý|Note|Lưu ý|Tip|Mẹo):/i;
+const LABEL_CLASS = (word: string) =>
+  /^(error|lỗi|caution|danger|breaking)$/i.test(word)
+    ? "text-status-danger"
+    : /^(warning|cảnh báo|important|quan trọng|chú ý)$/i.test(word)
+      ? "text-status-warning"
+      : "text-accent";
+
+function UrlLink({ url }: { url: string }) {
+  return (
+    <a href={url} target="_blank" rel="noopener noreferrer" className={LINK_CLASS}>
+      {url}
+    </a>
+  );
+}
+
+/** A path as a button that opens it, or as it was when nothing can. */
+function PathLink({ path, children }: { path: string; children: React.ReactNode }) {
+  const open = React.useContext(OpenFileContext);
+  if (!open) return <>{children}</>;
+  return (
+    <button
+      type="button"
+      title={path}
+      onClick={() => open(path)}
+      className={`${LINK_CLASS} text-left`}
+    >
+      {children}
+    </button>
+  );
+}
+
+/** Plain text with its URLs and absolute paths as links — nothing else parsed. */
+export function linkify(text: string): React.ReactNode[] {
+  const out: React.ReactNode[] = [];
+  let buf = "";
+  for (let i = 0; i < text.length;) {
+    const rest = text.slice(i);
+    const url = atWordStart(text, i) && URL_RE.exec(rest)?.[0];
+    const path = !url && atWordStart(text, i) && PATH_RE.exec(rest)?.[0];
+    const hit = url || path;
+    if (!hit) {
+      buf += text[i++];
+      continue;
+    }
+    if (buf) out.push(buf);
+    buf = "";
+    out.push(
+      url ? (
+        <UrlLink key={i} url={url} />
+      ) : (
+        <PathLink key={i} path={hit}>
+          {hit}
+        </PathLink>
+      )
+    );
+    i += hit.length;
+  }
+  if (buf) out.push(buf);
+  return out;
+}
+
 /** Render inline markdown (bold/italic/code/strikethrough/links/auto-links). */
 function renderInline(text: string, baseKey = ""): React.ReactNode[] {
   const out: React.ReactNode[] = [];
@@ -267,11 +353,18 @@ function renderInline(text: string, baseKey = ""): React.ReactNode[] {
     // Inline code: `...`
     const codeM = rest.match(/^`([^`\n]+)`/);
     if (codeM) {
-      push(
+      const code = (
         <code className="rounded bg-surface-4 border border-surface-3 px-1.5 py-0.5 font-mono text-[12.5px] text-status-warning">
           {codeM[1]}
         </code>
       );
+      push(
+        PATH_RE.exec(codeM[1]!)?.[0] === codeM[1] ? (
+          <PathLink path={codeM[1]!}>{code}</PathLink>
+        ) : (
+          code
+        )
+      );
       i += codeM[0].length;
       continue;
     }
@@ -280,7 +373,7 @@ function renderInline(text: string, baseKey = ""): React.ReactNode[] {
     const boldM = rest.match(/^(\*\*|__)(.+?)\1/);
     if (boldM) {
       push(
-        <strong className="font-semibold text-fg-primary">
+        <strong className="font-bold text-accent">
           {renderInline(boldM[2]!, `${baseKey}-b${n}`)}
         </strong>
       );
@@ -330,22 +423,39 @@ function renderInline(text: string, baseKey = ""): React.ReactNode[] {
     }
 
     // Auto-link
-    const urlM = rest.match(/^https?:\/\/[^\s<>()]+[^\s<>().,!?;:'"]/);
+    const urlM = rest.match(URL_RE);
     if (urlM) {
-      push(
-        <a
-          href={urlM[0]}
-          target="_blank"
-          rel="noopener noreferrer"
-          className="text-violet-700 dark:text-violet-300 hover:text-violet-800 dark:hover:text-violet-200 underline underline-offset-2 decoration-violet-400/40 hover:decoration-violet-300/70 break-all"
-        >
-          {urlM[0]}
-        </a>
-      );
+      push(<UrlLink url={urlM[0]} />);
       i += urlM[0].length;
       continue;
     }
 
+    // An absolute path at a word start
+    const pathM = atWordStart(text, i) ? PATH_RE.exec(rest) : null;
+    if (pathM) {
+      push(<PathLink path={pathM[0]}>{pathM[0]}</PathLink>);
+      i += pathM[0].length;
+      continue;
+    }
+
+    const labelM = atWordStart(text, i) ? LABEL_RE.exec(rest) : null;
+    if (labelM) {
+      push(<span className={`font-bold ${LABEL_CLASS(labelM[1]!)}`}>{labelM[0]}</span>);
+      i += labelM[0].length;
+      continue;
+    }
+
+    const numM = numStart(text, i) ? NUM_RE.exec(rest) : null;
+    if (numM) {
+      push(
+        <span className="font-semibold tabular-nums text-teal-700 dark:text-teal-300">
+          {numM[0]}
+        </span>
+      );
+      i += numM[0].length;
+      continue;
+    }
+
     buf += text[i]!;
     i++;
   }
@@ -381,6 +491,8 @@ interface MarkdownContentProps {
   text: string;
   /** Tighter spacing for nested contexts (list items, quotes). */
   dense?: boolean;
+  /** The assistant's reply in a chat: larger serif body text, as Claude Desktop. */
+  prose?: boolean;
 }
 
 const HEADING_STYLES = [
@@ -392,12 +504,16 @@ const HEADING_STYLES = [
   "text-xs font-medium text-fg-secondary uppercase tracking-wider",
 ];
 
-export function MarkdownContent({ text, dense = false }: MarkdownContentProps) {
+export function MarkdownContent({ text, dense = false, prose = false }: MarkdownContentProps) {
   const blocks = parseBlocks(text);
   const gap = dense ? "space-y-1.5" : "space-y-2.5";
+  // A paragraph or list item takes the root's size and colour in prose.
+  const bodyText = prose ? "" : "text-sm text-fg-secondary";
 
   return (
-    <div className={`text-sm text-fg-secondary leading-relaxed ${gap}`}>
+    <div
+      className={`${prose ? "font-serif text-[15px] leading-7 text-fg-primary" : "text-sm text-fg-secondary leading-relaxed"} ${gap}`}
+    >
       {blocks.map((b, idx) => {
         switch (b.kind) {
           case "code":
@@ -420,7 +536,7 @@ export function MarkdownContent({ text, dense = false }: MarkdownContentProps) {
                   className="list-decimal pl-5 space-y-1 marker:text-fg-muted marker:font-mono marker:text-xs"
                 >
                   {b.items.map((item, i) => (
-                    <li key={i} className="text-sm text-fg-secondary">
+                    <li key={i} className={bodyText}>
                       {renderListItem(item, `li${idx}-${i}`)}
                     </li>
                   ))}
@@ -433,7 +549,7 @@ export function MarkdownContent({ text, dense = false }: MarkdownContentProps) {
                 className="list-disc pl-5 space-y-1 marker:text-violet-700/60 dark:marker:text-violet-400/60"
               >
                 {b.items.map((item, i) => (
-                  <li key={i} className="text-sm text-fg-secondary">
+                  <li key={i} className={bodyText}>
                     {renderListItem(item, `li${idx}-${i}`)}
                   </li>
                 ))}
@@ -503,7 +619,7 @@ export function MarkdownContent({ text, dense = false }: MarkdownContentProps) {
 
           case "para":
             return (
-              <p key={idx} className="text-sm text-fg-secondary whitespace-pre-wrap break-words">
+              <p key={idx} className={`${bodyText} whitespace-pre-wrap break-words`}>
                 {renderInline(b.text, `p${idx}`)}
               </p>
             );

client/src/components/conversation/MessageList.tsx

@@ -4,7 +4,21 @@
  * transcript: alternating user / assistant rows with collapsible thinking
  * blocks, inline ToolCallBlocks for tool_use / tool_result pairs, and
  * MarkdownContent for prose. Used by ConversationView as the main body of
- * the Conversation tab on the Session detail page.
+ * the Conversation tab on the Session detail page. An image the prompt box
+ * attached reaches the transcript as its saved path; a user turn shows the
+ * image instead (`GET /api/run/drop/:name`), and Claude Code's own
+ * `[Image: source: <drop>]` line for it joins that turn rather than showing as
+ * a System row; URLs and absolute paths in a turn are links (a path opens
+ * through `onOpenFile`), and its `/command` and `@path` tokens chips coloured
+ * like the prompt box's (`lib/promptTokens.ts`). Each assistant turn that changed
+ * files ends with Claude Desktop's "Edited N files" card: every file with the
+ * lines added and removed (the tool results' `diff`); a click opens the file
+ * when the caller can (`onOpenFile`), and a row (or the card's header, for
+ * every file in it) drags into a prompt box as an `@path` attachment. A thinking block that carries text is
+ * the model's narration to the user (Claude Code ≥ 2.1.280 stores real
+ * thinking empty) and reads as prose, like Claude Desktop shows it; a live
+ * chat (`live`) ends, until its turn is over, with what the model is doing
+ * now — the call still running, else "Thinking…" — and for how long.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 /* =============================================================================
@@ -53,7 +67,8 @@
  *
  * ----------------------------------------------------------------------------- */
 
-import { memo, useState, useMemo } from "react";
+import { Fragment, memo, useEffect, useState, useMemo } from "react";
+import { ImageLightbox } from "../ImageLightbox";
 import { useTranslation } from "react-i18next";
 import i18n from "../../i18n";
 import {
@@ -69,6 +84,8 @@ import {
   Pencil,
   Workflow,
   Cog,
+  FileText,
+  Loader2,
 } from "lucide-react";
 import type { TranscriptMessage, TranscriptContent, TranscriptSender } from "../../lib/types";
 
@@ -111,14 +128,20 @@ const SENDER_STYLES: Record<
     headerText: "text-status-warning",
   },
 };
-import { ToolCallBlock } from "./ToolCallBlock";
-import { MarkdownContent } from "./MarkdownContent";
-import { fmt, formatModelName } from "../../lib/format";
+import { ToolCallBlock, buildSummary, renderInput, renderResult } from "./ToolCallBlock";
+import { MarkdownContent, OpenFileContext, linkify } from "./MarkdownContent";
+import { dragAttachments, projectAttachment } from "../../lib/promptAttach";
+import { TOKEN_TONE, promptTokens as splitPrompt } from "../../lib/promptTokens";
+import { fmt, formatModelName, formatMs, parseDate } from "../../lib/format";
 import { parseTuiSegments, stripAnsi, hasTuiTags, type TuiSegment } from "./tuiSegments";
 
 interface MessageListProps {
   messages: TranscriptMessage[];
   loading: boolean;
+  /** Opens a file named in the "Edited N files" card. */
+  onOpenFile?: (path: string) => void;
+  /** The session is running in a pane: show the step in progress. */
+  live?: boolean;
 }
 
 /** Build a map from tool_use id → tool_result for matching */
@@ -135,6 +158,16 @@ function buildToolResultMap(messages: TranscriptMessage[]): Map<string, Transcri
   return map;
 }
 
+/** The whole prompt a message was answered from: `input_tokens` is only its
+ *  uncached tail (a few tokens once the cache is warm), the rest is cache. */
+function promptTokens(u: NonNullable<TranscriptMessage["usage"]>): number {
+  return (
+    (u.input_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0)
+  );
+}
+const usageTitle = (u: NonNullable<TranscriptMessage["usage"]>) =>
+  `input ${fmt(u.input_tokens || 0)} · cache read ${fmt(u.cache_read_input_tokens || 0)} · cache write ${fmt(u.cache_creation_input_tokens || 0)} · output ${fmt(u.output_tokens || 0)}`;
+
 /** Detect if text is skill loading content (starts with "Base directory for this skill:") */
 function isSkillContent(text: string): boolean {
   return text.startsWith("Base directory for this skill:");
@@ -174,12 +207,32 @@ function SessionEventRow({ title, timestamp }: { title?: string; timestamp: stri
   );
 }
 
-/** Compact pill for /command invocations parsed out of TUI markup. */
+/** Typed text with its `/command` and `@path` tokens as chips, the rest linkified. */
+function typedText(text: string): React.ReactNode[] {
+  return splitPrompt(text).map((tok, i) =>
+    tok.kind === "text" ? (
+      <Fragment key={i}>{linkify(tok.text)}</Fragment>
+    ) : (
+      <span
+        key={i}
+        className={`rounded-md px-1.5 py-0.5 font-mono text-[0.92em] font-medium ${TOKEN_TONE[tok.kind]}`}
+      >
+        {tok.text}
+      </span>
+    )
+  );
+}
+
+/** Compact pill for /command invocations parsed out of TUI markup: the
+ *  command in the prompt box's colour, its arguments after it. */
 function CommandPill({ display }: { display: string }) {
+  const [name, ...args] = display.split(" ");
   return (
-    <div className="inline-flex items-center gap-2 text-sm text-status-success font-mono bg-status-success/10 border border-status-success/20 rounded-md px-3 py-1.5 max-w-full">
-      <span className="text-status-success/70">›</span>
-      <span className="break-all">{display}</span>
+    <div className="inline-flex max-w-full items-baseline gap-2 rounded-lg border border-accent/25 bg-accent/10 px-2.5 py-1 font-mono text-sm">
+      <span className="font-semibold text-accent">{name}</span>
+      {args.length > 0 && (
+        <span className="break-all text-fg-secondary">{typedText(args.join(" "))}</span>
+      )}
     </div>
   );
 }
@@ -264,6 +317,60 @@ function renderSegment(seg: TuiSegment, key: number): React.ReactNode {
   }
 }
 
+/** A text block of any sender: a task notification or skill body collapsed,
+ *  TUI markup as segments, anything else as markdown. */
+function renderTextBlock(text: string, key: number): React.ReactNode {
+  // Detect task notifications, collapsed by default
+  if (isTaskNotification(text)) {
+    return (
+      <CollapsibleBlock
+        key={key}
+        text={text}
+        icon={<ScrollText className="w-3.5 h-3.5 text-syntax-property/70 flex-shrink-0" />}
+        title={i18n.t("sessions:conversation.taskNotification")}
+        borderClass="border-syntax-property/20"
+        bgClass="bg-syntax-property/5"
+        textClass="text-syntax-property"
+      />
+    );
+  }
+
+  // Detect skill content, collapsed by default
+  if (isSkillContent(text)) {
+    const pathMatch = text.match(/^Base directory for this skill:\s*(\S+)/);
+    const skillPath = pathMatch ? pathMatch[1]! : "Skill";
+    return (
+      <CollapsibleBlock
+        key={key}
+        text={text}
+        icon={<ScrollText className="w-3.5 h-3.5 text-syntax-builtin/70 flex-shrink-0" />}
+        title={skillPath}
+        borderClass="border-syntax-builtin/20"
+        bgClass="bg-syntax-builtin/5"
+        textClass="text-syntax-builtin"
+      />
+    );
+  }
+
+  // Mixed TUI markup: caveat / command / stdout / stderr / system-reminder
+  // can appear inline (sometimes interleaved with prose). Parse the text
+  // into segments and render each with the appropriate visual treatment.
+  if (hasTuiTags(text)) {
+    const segments = parseTuiSegments(text);
+    return (
+      <div key={key} className="space-y-2 min-w-0">
+        {segments.map((s, sIdx) => renderSegment(s, sIdx))}
+      </div>
+    );
+  }
+
+  return (
+    <div key={key} className="min-w-0">
+      <MarkdownContent text={stripAnsi(text)} />
+    </div>
+  );
+}
+
 /** Generic collapsible content block */
 function CollapsibleBlock({
   text,
@@ -326,10 +433,157 @@ export function messageKeys(messages: TranscriptMessage[]): string[] {
   });
 }
 
-export function MessageList({ messages, loading }: MessageListProps) {
+/** One thing on screen, in the Claude Desktop layout: a human message as a
+ *  bubble, the assistant's prose bare, and everything it did between two
+ *  pieces of prose — tool calls and thinking, across messages (Claude Code
+ *  writes each as its own line) — as ONE collapsed line; any other sender
+ *  keeps its attributed row. */
+type Item =
+  | { kind: "event"; key: string; msg: TranscriptMessage }
+  | { kind: "row"; key: string; msg: TranscriptMessage }
+  | { kind: "user"; key: string; msg: TranscriptMessage }
+  | { kind: "text"; key: string; msg: TranscriptMessage; text: string }
+  | { kind: "work"; key: string; blocks: TranscriptContent[] }
+  | { kind: "edits"; key: string; blocks: TranscriptContent[] };
+
+const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+export function chatItems(messages: TranscriptMessage[], keys: string[]): Item[] {
+  const items: Item[] = [];
+  // The file-changing calls of the turn so far, closed into one card when the
+  // human speaks again (or the list ends).
+  let edits: TranscriptContent[] = [];
+  const endTurn = (key: string) => {
+    if (edits.length) items.push({ kind: "edits", key: `edits:${key}`, blocks: edits });
+    edits = [];
+  };
+  messages.forEach((msg, idx) => {
+    const key = keys[idx]!;
+    if (msg.type === "session_event") return items.push({ kind: "event", key, msg });
+    // Purely tool_result: shown inside its call's block.
+    if (msg.type === "user" && !msg.content.some((c) => c.type === "text")) return;
+    const sender = msg.sender ?? (msg.type === "assistant" ? "assistant" : "user");
+    if (sender === "user") {
+      endTurn(key);
+      return items.push({ kind: "user", key, msg });
+    }
+    if (sender !== "assistant") {
+      // Claude Code's line for the image a prompt attached: the image joins that prompt.
+      const paths = sender === "system" ? imageSourcePaths(msg) : null;
+      const prompt = paths ? [...items].reverse().find((i) => i.kind === "user") : undefined;
+      if (paths && prompt?.kind === "user") {
+        prompt.msg = {
+          ...prompt.msg,
+          content: [
+            ...prompt.msg.content.map((c) =>
+              c.type === "text" && c.text
+                ? { ...c, text: c.text.replace(/\[Image #\d+\]/g, "") }
+                : c
+            ),
+            { type: "text", text: paths.join("\n") },
+          ],
+        };
+        return;
+      }
+      return items.push({ kind: "row", key, msg });
+    }
+    msg.content.forEach((block, b) => {
+      const last = items[items.length - 1];
+      if (block.type === "tool_use" && EDIT_TOOLS.has(block.name ?? "")) edits.push(block);
+      if (block.type === "tool_use") {
+        if (last?.kind === "work") last.blocks.push(block);
+        else items.push({ kind: "work", key: `${key}:${b}`, blocks: [block] });
+      } else if ((block.type === "text" || block.type === "thinking") && block.text?.trim()) {
+        items.push({ kind: "text", key: `${key}:${b}`, msg, text: block.text });
+      }
+    });
+  });
+  endTurn(keys[keys.length - 1] ?? "end");
+  return items;
+}
+
+/** Claude Desktop's end-of-turn card: the files the turn changed, each with
+ *  the lines added and removed. A call still running or failed is left out. */
+function EditedFiles({
+  blocks,
+  toolResultMap,
+  onOpenFile,
+}: {
+  blocks: TranscriptContent[];
+  toolResultMap: Map<string, TranscriptContent>;
+  onOpenFile?: (path: string) => void;
+}) {
+  const { t } = useTranslation("sessions");
+  // `counted`: a result carried its +/- lines (an older server sends none).
+  const files = new Map<string, { added: number; removed: number; counted: boolean }>();
+  for (const b of blocks) {
+    const input = (b.input ?? {}) as Record<string, unknown>;
+    const p = input.file_path ?? input.notebook_path;
+    const r = b.id ? toolResultMap.get(b.id) : undefined;
+    if (typeof p !== "string" || !r || r.is_error) continue;
+    const f = files.get(p) ?? { added: 0, removed: 0, counted: false };
+    f.added += r.diff?.added ?? 0;
+    f.removed += r.diff?.removed ?? 0;
+    f.counted ||= !!r.diff;
+    files.set(p, f);
+  }
+  if (files.size === 0) return null;
+  let added = 0;
+  let removed = 0;
+  let counted = false;
+  files.forEach((f) => {
+    added += f.added;
+    removed += f.removed;
+    counted ||= f.counted;
+  });
+  const counts = (a: number, r: number, show = counted) =>
+    show && (
+      <span className="flex-shrink-0 font-mono text-xs">
+        <span className="text-status-success">+{a}</span>{" "}
+        <span className="text-status-danger">−{r}</span>
+      </span>
+    );
+  return (
+    <div data-testid="edited-files" className="overflow-hidden rounded-xl border border-border">
+      <div
+        draggable
+        onDragStart={(e) => dragAttachments(e, [...files.keys()].map(projectAttachment))}
+        className="flex cursor-grab items-center gap-2 border-b border-border bg-surface-1 px-3 py-2 text-sm text-fg-primary"
+      >
+        <Pencil className="h-3.5 w-3.5 text-fg-muted" />
+        <span className="flex-1">{t("conversation.edited", { count: files.size })}</span>
+        {counts(added, removed)}
+      </div>
+      {[...files].map(([p, f]) => (
+        <button
+          key={p}
+          type="button"
+          title={p}
+          disabled={!onOpenFile}
+          onClick={() => onOpenFile?.(p)}
+          draggable
+          onDragStart={(e) => dragAttachments(e, [projectAttachment(p)])}
+          className="flex w-full items-center gap-2 border-b border-border px-3 py-2 text-left text-sm text-fg-secondary last:border-b-0 enabled:hover:bg-surface-2"
+        >
+          <FileText className="h-3.5 w-3.5 flex-shrink-0 text-fg-muted" />
+          <span className="min-w-0 flex-1 truncate">{p.split("/").pop()}</span>
+          {counts(f.added, f.removed, f.counted)}
+          {onOpenFile && <ChevronRight className="h-3.5 w-3.5 flex-shrink-0 text-fg-muted" />}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+export function MessageList({ messages, loading, onOpenFile, live = false }: MessageListProps) {
   const { t } = useTranslation("sessions");
   const toolResultMap = useMemo(() => buildToolResultMap(messages), [messages]);
+  const pending = useMemo(
+    () => (live ? workingOn(messages, toolResultMap) : null),
+    [live, messages, toolResultMap]
+  );
   const keys = useMemo(() => messageKeys(messages), [messages]);
+  const items = useMemo(() => chatItems(messages, keys), [messages, keys]);
 
   if (loading) {
     return (
@@ -344,23 +598,445 @@ export function MessageList({ messages, loading }: MessageListProps) {
   }
 
   return (
-    <div className="space-y-3">
-      {messages.map((msg, idx) => {
-        // Session lifecycle markers (e.g. /rename) render as a centered chip,
-        // not as a user/assistant row.
-        if (msg.type === "session_event") {
-          return <SessionEventRow key={keys[idx]} title={msg.title} timestamp={msg.timestamp} />;
-        }
-        // Skip user messages that are purely tool_result - they're rendered inside ToolCallBlock
-        if (msg.type === "user" && !msg.content.some((c) => c.type === "text")) {
-          return null;
-        }
-        return <MessageRow key={keys[idx]} msg={msg} toolResultMap={toolResultMap} />;
-      })}
+    <OpenFileContext.Provider value={onOpenFile}>
+      <div className="mx-auto w-full max-w-[max(48rem,70%)] space-y-4 px-4 py-4">
+        {items.map((item) => {
+          switch (item.kind) {
+            case "event":
+              return (
+                <SessionEventRow
+                  key={item.key}
+                  title={item.msg.title}
+                  timestamp={item.msg.timestamp}
+                />
+              );
+            case "row":
+              return <MessageRow key={item.key} msg={item.msg} toolResultMap={toolResultMap} />;
+            case "user":
+              return <UserBubble key={item.key} msg={item.msg} />;
+            case "text":
+              return <AssistantText key={item.key} msg={item.msg} text={item.text} />;
+            case "work":
+              return (
+                <WorkGroup key={item.key} blocks={item.blocks} toolResultMap={toolResultMap} />
+              );
+            case "edits":
+              // The card closes a finished turn; one still working has none yet.
+              if (pending && item === items[items.length - 1]) return null;
+              return (
+                <EditedFiles
+                  key={item.key}
+                  blocks={item.blocks}
+                  toolResultMap={toolResultMap}
+                  onOpenFile={onOpenFile}
+                />
+              );
+          }
+        })}
+        {pending && <RunningStep block={pending.block} since={pending.since} />}
+      </div>
+    </OpenFileContext.Provider>
+  );
+}
+
+// No line for this long and no call running: the turn died with no end
+// written (a crash, a kill) — stop saying it works.
+const IDLE_AFTER_MS = 15 * 60_000;
+
+/** What the model is doing while its turn is not over: the call still
+ *  waiting for its result (`block`), else thinking (`block: null`); `since`
+ *  is that line's time. Null once the turn ended. */
+export function workingOn(
+  messages: TranscriptMessage[],
+  results: Map<string, TranscriptContent>,
+  now = Date.now()
+): { block: TranscriptContent | null; since: string | null } | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]!;
+    const sender = msg.sender ?? (msg.type === "assistant" ? "assistant" : "user");
+    // A rename marker or a harness line says nothing about the turn.
+    if (msg.type === "session_event" || sender === "system" || sender === "orchestrator") continue;
+    const since = msg.timestamp ?? null;
+    const fresh = !since || now - parseDate(since).getTime() < IDLE_AFTER_MS;
+    if (msg.type === "assistant") {
+      const call = [...msg.content].reverse().find((b) => b.type === "tool_use");
+      if (call?.id && !results.has(call.id)) return { block: call, since };
+      // "tool_use": a call follows. "end_turn" (or none, from an older server): over.
+      return msg.stop_reason === "tool_use" && fresh ? { block: null, since } : null;
+    }
+    // A prompt or a tool result: the model answers it next — unless the user stopped it.
+    const text = msg.content.find((c) => c.type === "text")?.text ?? "";
+    if (text.startsWith("[Request interrupted")) return null;
+    return fresh ? { block: null, since } : null;
+  }
+  return null;
+}
+
+/** Claude Desktop's live line: the step running now and for how long. */
+function RunningStep({ block, since }: { block: TranscriptContent | null; since: string | null }) {
+  const { t } = useTranslation("sessions");
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const timer = window.setInterval(() => setNow(Date.now()), 1000);
+    return () => window.clearInterval(timer);
+  }, []);
+  const input = block?.input as Record<string, unknown> | undefined;
+  const title = !block
+    ? t("conversation.working")
+    : typeof input?.description === "string" && input.description
+      ? input.description
+      : [block.name, buildSummary(block)].filter(Boolean).join(" ");
+  return (
+    <div data-testid="chat-running-step" className="flex items-center gap-2 text-sm text-fg-muted">
+      <Loader2 className="h-3.5 w-3.5 flex-shrink-0 animate-spin text-accent" />
+      <span className="min-w-0 truncate">{title}</span>
+      {since && (
+        <span className="flex-shrink-0 font-mono text-xs">
+          {formatMs(now - parseDate(since).getTime())}
+        </span>
+      )}
     </div>
   );
 }
 
+const meta = "text-[10px] font-mono text-fg-muted";
+
+// What the prompt box sends for an attached image: its saved path under the
+// drop dir (`<data dir>/drops/<16 hex>[-name].png`, server/routes/run.js; the
+// older `<tmp>/agenthub-drops-<uid>/` still in past transcripts).
+const DROP_IMAGE =
+  /(?<=^|\s)\S*[\\/](?:agenthub-drops--?\d+|drops)[\\/]([0-9a-f]{16}(?:-[A-Za-z0-9._-]+)?\.(?:png|jpe?g|gif|webp))(?=\s|$)/gi;
+// Claude Code's own line for an image it read off a pasted path (`isMeta`).
+const IMAGE_SOURCE = /^\[Image: source: (.+)\]$/;
+
+/** A user turn's text without its dropped-image paths (and Claude Code's
+ *  `[Image #N]` placeholders for them), and those images' names. */
+export function splitDropImages(text: string): { text: string; images: string[] } {
+  const images: string[] = [];
+  const rest = text.replace(DROP_IMAGE, (_all, name: string) => {
+    images.push(name);
+    return "";
+  });
+  return {
+    text: images.length
+      ? rest
+          .replace(/\[Image #\d+\]/g, "")
+          .replace(/[ \t]+$/gm, "")
+          .trim()
+      : text,
+    images,
+  };
+}
+
+/** The drop paths of a meta message made only of `[Image: source: <drop>]` lines. */
+function imageSourcePaths(msg: TranscriptMessage): string[] | null {
+  const lines = msg.content.flatMap((c) => (c.type === "text" ? (c.text ?? "").split("\n") : []));
+  const paths = lines.map((l) => IMAGE_SOURCE.exec(l.trim())?.[1] ?? "");
+  return paths.length && paths.every((p) => splitDropImages(p).images.length) ? paths : null;
+}
+
+function DropImage({ name }: { name: string }) {
+  const [open, setOpen] = useState(false);
+  const [gone, setGone] = useState(false);
+  const src = `/api/run/drop/${encodeURIComponent(name)}`;
+  // Drops are pruned after a day: the name is all that is left to show.
+  if (gone)
+    return (
+      <span className="flex items-center gap-1.5 rounded-lg border border-border bg-surface-2 px-2 py-1 text-xs text-fg-muted">
+        <FileText className="h-3.5 w-3.5 shrink-0" />
+        <span className="truncate">{name.replace(/^[0-9a-f]{16}-?/, "") || name}</span>
+      </span>
+    );
+  return (
+    <>
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className="block overflow-hidden rounded-xl border border-border bg-surface-2 hover:border-accent/50"
+      >
+        <img
+          src={src}
+          alt={name}
+          loading="lazy"
+          onError={() => setGone(true)}
+          className="max-h-48 max-w-64 object-contain"
+        />
+      </button>
+      {open && <ImageLightbox src={src} alt={name} onClose={() => setOpen(false)} />}
+    </>
+  );
+}
+
+/** The human's turn: a bubble on the right, its time on hover. A long one (a
+ *  paste, a compaction summary) shows its first lines until opened. */
+const LONG_BUBBLE = 800;
+const UserBubble = memo(function UserBubble({ msg }: { msg: TranscriptMessage }) {
+  const { t } = useTranslation("sessions");
+  const long = msg.content.reduce((n, c) => n + (c.text?.length ?? 0), 0) > LONG_BUBBLE;
+  const [open, setOpen] = useState(false);
+  const blocks = useMemo(
+    () =>
+      msg.content.map((block) =>
+        block.type === "text" && block.text ? splitDropImages(block.text) : null
+      ),
+    [msg.content]
+  );
+  const images = blocks.flatMap((b) => b?.images ?? []);
+  const hasText = blocks.some((b) => b?.text);
+  return (
+    <div
+      data-testid="chat-user"
+      style={{ contentVisibility: "auto", containIntrinsicSize: "auto 60px" }}
+      className="group flex flex-col items-end gap-1"
+    >
+      {images.length > 0 && (
+        <div
+          data-testid="chat-user-images"
+          className="flex max-w-[85%] flex-wrap justify-end gap-2"
+        >
+          {images.map((name) => (
+            <DropImage key={name} name={name} />
+          ))}
+        </div>
+      )}
+      {hasText && (
+        <div
+          className={`max-w-[85%] min-w-0 space-y-2 rounded-2xl bg-surface-2 px-4 py-2.5 text-sm text-fg-primary ${
+            long && !open
+              ? "max-h-40 overflow-hidden [mask-image:linear-gradient(to_bottom,black_60%,transparent)]"
+              : ""
+          }`}
+        >
+          {blocks.map((block, b) => {
+            const text = block?.text;
+            if (!text) return null;
+            // Plain typing reads as typed; anything structured keeps its rendering.
+            const plain = !hasTuiTags(text) && !isSkillContent(text) && !isTaskNotification(text);
+            return plain ? (
+              <p key={b} className="whitespace-pre-wrap break-words leading-relaxed">
+                {typedText(stripAnsi(text).trim())}
+              </p>
+            ) : (
+              renderTextBlock(text, b)
+            );
+          })}
+        </div>
+      )}
+      {long && (
+        <button
+          type="button"
+          aria-expanded={open}
+          onClick={() => setOpen(!open)}
+          className="text-xs text-fg-muted hover:text-fg-secondary"
+        >
+          {open ? t("conversation.showLess") : t("conversation.showMore")}
+        </button>
+      )}
+      {msg.timestamp && (
+        <span className={`${meta} opacity-0 transition-opacity group-hover:opacity-100`}>
+          {formatLocalTime(msg.timestamp)}
+        </span>
+      )}
+    </div>
+  );
+});
+
+/** The assistant's prose, bare on the page; model, tokens and time on hover. */
+const AssistantText = memo(function AssistantText({
+  msg,
+  text,
+}: {
+  msg: TranscriptMessage;
+  text: string;
+}) {
+  return (
+    <div
+      data-testid="chat-assistant"
+      style={{ contentVisibility: "auto", containIntrinsicSize: "auto 120px" }}
+      className="group min-w-0"
+    >
+      {hasTuiTags(text) || isSkillContent(text) || isTaskNotification(text) ? (
+        renderTextBlock(text, 0)
+      ) : (
+        <MarkdownContent text={stripAnsi(text)} prose />
+      )}
+      <div
+        className={`${meta} mt-1 flex gap-2 opacity-0 transition-opacity group-hover:opacity-100`}
+      >
+        {msg.model && <span>{formatModelName(msg.model)}</span>}
+        {msg.usage && (
+          <span title={usageTitle(msg.usage)}>
+            ↓ {fmt(promptTokens(msg.usage))} · ↑ {fmt(msg.usage.output_tokens)}
+          </span>
+        )}
+        {msg.timestamp && <span>{formatLocalTime(msg.timestamp)}</span>}
+      </div>
+    </div>
+  );
+});
+
+/** A muted line that opens to show what it stands for. */
+function Disclosure({ label, children }: { label: string; children: React.ReactNode }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <div>
+      <button
+        type="button"
+        aria-expanded={open}
+        onClick={() => setOpen(!open)}
+        className="inline-flex items-center gap-1 text-sm text-fg-muted transition-colors hover:text-fg-secondary"
+      >
+        {label}
+        <ChevronRight className={`h-3.5 w-3.5 transition-transform ${open ? "rotate-90" : ""}`} />
+      </button>
+      {open && <div className="mt-2 space-y-2">{children}</div>}
+    </div>
+  );
+}
+
+/** The kind of work a tool call is, for the group's label (Claude Code and
+ *  Codex names); anything else counts as a tool. */
+const WORK_KIND: Record<string, string> = {
+  bash: "commands",
+  shell: "commands",
+  exec_command: "commands",
+  powershell: "commands",
+  edit: "edits",
+  multiedit: "edits",
+  write: "edits",
+  notebookedit: "edits",
+  apply_patch: "edits",
+  read: "reads",
+  grep: "searches",
+  glob: "searches",
+  ls: "searches",
+  websearch: "web",
+  webfetch: "web",
+  task: "agents",
+  agent: "agents",
+};
+
+/** "Ran 3 commands, edited 2 files" — or "Thinking" when it only thought. */
+const KIND_ORDER = ["commands", "edits", "reads", "searches", "web", "agents", "tools"];
+
+export function workLabel(blocks: TranscriptContent[]): string {
+  const counts = new Map<string, number>();
+  for (const b of blocks) {
+    if (b.type !== "tool_use") continue;
+    const kind = WORK_KIND[(b.name ?? "").toLowerCase()] ?? "tools";
+    counts.set(kind, (counts.get(kind) ?? 0) + 1);
+  }
+  if (!counts.size) return i18n.t("sessions:conversation.thinking");
+  // Claude Desktop's order: commands, edits, reads, … and other tools last.
+  const text = [...counts]
+    .sort(([a], [b]) => KIND_ORDER.indexOf(a) - KIND_ORDER.indexOf(b))
+    .map(([kind, count]) => i18n.t(`sessions:conversation.work.${kind}`, { count }))
+    .join(", ");
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+/** One step inside an opened group, as Claude Desktop lists them: its own
+ *  description (Claude Code's Bash `description`) or the tool and target as
+ *  the title, the call itself under it in a capped scroll box, the result one
+ *  click further. Thinking is a step too, closed. */
+function WorkStep({
+  block,
+  result,
+}: {
+  block: TranscriptContent;
+  result: TranscriptContent | null;
+}) {
+  const { t } = useTranslation("sessions");
+  const thinking = block.type === "thinking";
+  const [open, setOpen] = useState(!thinking);
+  const [showResult, setShowResult] = useState(false);
+  const input = block.input as Record<string, unknown> | undefined;
+  const title = thinking
+    ? t("conversation.thinking")
+    : typeof input?.description === "string" && input.description
+      ? input.description
+      : [block.name, buildSummary(block)].filter(Boolean).join(" ");
+  return (
+    <div className="px-3 py-2">
+      <button
+        type="button"
+        aria-expanded={open}
+        onClick={() => setOpen(!open)}
+        className={`flex w-full min-w-0 items-center gap-1 text-left text-sm transition-colors hover:text-fg-secondary ${
+          result?.is_error ? "text-status-danger" : "text-fg-muted"
+        }`}
+      >
+        <span className="truncate">{title}</span>
+        <ChevronDown
+          className={`h-3.5 w-3.5 shrink-0 transition-transform ${open ? "" : "-rotate-90"}`}
+        />
+      </button>
+      {open && (
+        <div className="mt-2 space-y-2">
+          {thinking ? (
+            <div className="max-h-60 overflow-auto text-fg-muted">
+              <MarkdownContent text={block.text ?? ""} dense />
+            </div>
+          ) : (
+            <>
+              <div className="max-h-60 overflow-auto">
+                {/* The description is the title already. */}
+                {renderInput(
+                  input ? { ...block, input: { ...input, description: undefined } } : block
+                )}
+              </div>
+              {result && (
+                <button
+                  type="button"
+                  aria-expanded={showResult}
+                  onClick={() => setShowResult(!showResult)}
+                  className="inline-flex items-center gap-1 text-xs text-fg-muted hover:text-fg-secondary"
+                >
+                  {result.is_error ? t("conversation.tool.error") : t("conversation.tool.output")}
+                  <ChevronRight
+                    className={`h-3 w-3 transition-transform ${showResult ? "rotate-90" : ""}`}
+                  />
+                </button>
+              )}
+              {result && showResult && (
+                <div className="max-h-60 overflow-auto">
+                  {renderResult(result, block.name ?? "")}
+                </div>
+              )}
+            </>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** What the assistant did between two replies as one line, opening onto
+ *  one framed list of its steps. */
+const WorkGroup = memo(function WorkGroup({
+  blocks,
+  toolResultMap,
+}: {
+  blocks: TranscriptContent[];
+  toolResultMap: ReturnType<typeof buildToolResultMap>;
+}) {
+  return (
+    <div data-testid="chat-tools">
+      <Disclosure label={workLabel(blocks)}>
+        <div className="divide-y divide-border overflow-hidden rounded-xl border border-border">
+          {blocks.map((block, i) => (
+            <WorkStep
+              key={block.id ?? i}
+              block={block}
+              result={block.id ? (toolResultMap.get(block.id) ?? null) : null}
+            />
+          ))}
+        </div>
+      </Disclosure>
+    </div>
+  );
+});
+
 /** One user/assistant row. Memoized: a live tail append re-renders only the
  *  new rows; its thinking-block expansion is its own state, kept by key. */
 const MessageRow = memo(function MessageRow({
@@ -404,8 +1080,11 @@ const MessageRow = memo(function MessageRow({
             </span>
           )}
           {msg.usage && (
-            <span className="text-[10px] text-fg-muted font-mono inline-flex items-center gap-1">
-              <span className="text-status-success/70">↓ {fmt(msg.usage.input_tokens)}</span>
+            <span
+              title={usageTitle(msg.usage)}
+              className="text-[10px] text-fg-muted font-mono inline-flex items-center gap-1"
+            >
+              <span className="text-status-success/70">↓ {fmt(promptTokens(msg.usage))}</span>
               <span className="text-fg-muted">·</span>
               <span className="text-syntax-number">↑ {fmt(msg.usage.output_tokens)}</span>
             </span>
@@ -419,59 +1098,7 @@ const MessageRow = memo(function MessageRow({
 
         {/* Content blocks */}
         {msg.content.map((block, bIdx) => {
-          if (block.type === "text" && block.text) {
-            // Detect task notifications, collapsed by default
-            if (isTaskNotification(block.text)) {
-              return (
-                <CollapsibleBlock
-                  key={bIdx}
-                  text={block.text}
-                  icon={
-                    <ScrollText className="w-3.5 h-3.5 text-syntax-property/70 flex-shrink-0" />
-                  }
-                  title={t("conversation.taskNotification")}
-                  borderClass="border-syntax-property/20"
-                  bgClass="bg-syntax-property/5"
-                  textClass="text-syntax-property"
-                />
-              );
-            }
-
-            // Detect skill content, collapsed by default
-            if (isSkillContent(block.text)) {
-              const pathMatch = block.text.match(/^Base directory for this skill:\s*(\S+)/);
-              const skillPath = pathMatch ? pathMatch[1]! : "Skill";
-              return (
-                <CollapsibleBlock
-                  key={bIdx}
-                  text={block.text}
-                  icon={<ScrollText className="w-3.5 h-3.5 text-syntax-builtin/70 flex-shrink-0" />}
-                  title={skillPath}
-                  borderClass="border-syntax-builtin/20"
-                  bgClass="bg-syntax-builtin/5"
-                  textClass="text-syntax-builtin"
-                />
-              );
-            }
-
-            // Mixed TUI markup: caveat / command / stdout / stderr / system-reminder
-            // can appear inline (sometimes interleaved with prose). Parse the text
-            // into segments and render each with the appropriate visual treatment.
-            if (hasTuiTags(block.text)) {
-              const segments = parseTuiSegments(block.text);
-              return (
-                <div key={bIdx} className="space-y-2 min-w-0">
-                  {segments.map((s, sIdx) => renderSegment(s, sIdx))}
-                </div>
-              );
-            }
-
-            return (
-              <div key={bIdx} className="min-w-0">
-                <MarkdownContent text={stripAnsi(block.text)} />
-              </div>
-            );
-          }
+          if (block.type === "text" && block.text) return renderTextBlock(block.text, bIdx);
 
           if (block.type === "thinking" && block.text) {
             const thinkKey = bIdx;

client/src/components/conversation/ToolCallBlock.tsx

@@ -94,7 +94,7 @@ function langFromPath(path: string): string {
 }
 
 /** Build a one-line summary of the tool call to show in the collapsed header. */
-function buildSummary(toolUse: TranscriptContent): string | null {
+export function buildSummary(toolUse: TranscriptContent): string | null {
   const input = toolUse.input;
   if (!input || typeof input !== "object" || "_truncated" in input) return null;
   const obj = input as Record<string, unknown>;
@@ -112,7 +112,7 @@ function buildSummary(toolUse: TranscriptContent): string | null {
 const tt = (key: string) => i18n.t(`sessions:conversation.tool.${key}`);
 
 /** Render the input pane with tool-aware formatting. */
-function renderInput(toolUse: TranscriptContent) {
+export function renderInput(toolUse: TranscriptContent) {
   const input = toolUse.input;
   if (!input) return null;
 
@@ -231,7 +231,7 @@ function renderInput(toolUse: TranscriptContent) {
 }
 
 /** Render the result pane: detect diff/json/text. */
-function renderResult(toolResult: TranscriptContent, toolName: string) {
+export function renderResult(toolResult: TranscriptContent, toolName: string) {
   const text = toolResult.output ?? "";
   if (text.length === 0)
     return <div className="text-xs text-fg-muted italic px-1">({tt("empty")})</div>;

client/src/components/conversation/__tests__/ConversationView.follow.test.tsx

@@ -0,0 +1,93 @@
+/**
+ * @file ConversationView.follow.test.tsx
+ * @description A chat sticks to its end: when it grows or is shown again
+ * after being hidden (a size change, which fires no scroll event) it scrolls
+ * to the newest while the reader is at the end, leaves a reader who scrolled
+ * up alone, and a send (`follow`) brings it back to the end.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ConversationView } from "../ConversationView";
+
+vi.mock("../../../lib/api", async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    api: {
+      sessions: {
+        transcripts: vi.fn(async () => ({ transcripts: [] })),
+        transcript: vi.fn(async () => ({
+          messages: [
+            {
+              type: "user",
+              content: [{ type: "text", text: "hello" }],
+              timestamp: "2026-10-09T00:00:00Z",
+            },
+          ],
+          total: 1,
+          has_more: false,
+          first_line: 1,
+          last_line: 1,
+        })),
+      },
+    },
+  };
+});
+
+let resize: (() => void) | null = null;
+const original = globalThis.ResizeObserver;
+beforeEach(() => {
+  resize = null;
+  // @ts-expect-error test stub
+  globalThis.ResizeObserver = class {
+    constructor(cb: () => void) {
+      resize = cb;
+    }
+    observe() {}
+    disconnect() {}
+  };
+  vi.spyOn(window, "requestAnimationFrame").mockImplementation((cb) => {
+    cb(0);
+    return 0;
+  });
+});
+afterEach(() => {
+  globalThis.ResizeObserver = original;
+  vi.restoreAllMocks();
+});
+
+/** The scroll box, with the layout jsdom does not compute. */
+function box(height: number) {
+  const el = screen.getByText("hello").closest(".overflow-y-auto") as HTMLElement;
+  Object.defineProperty(el, "scrollHeight", { configurable: true, value: height });
+  Object.defineProperty(el, "clientHeight", { configurable: true, value: 200 });
+  Object.defineProperty(el, "scrollTop", { configurable: true, writable: true, value: 0 });
+  return el;
+}
+
+describe("ConversationView sticks to its end", () => {
+  it("scrolls to the newest when it grows or is shown again, unless the reader scrolled up", async () => {
+    const view = render(<ConversationView sessionId="s1" fill live />);
+    await screen.findByText("hello");
+    const el = box(1000);
+    // Shown again after display:none, or taller: only a resize says so.
+    act(() => resize?.());
+    expect(el.scrollTop).toBe(1000);
+
+    // The reader scrolls up: growing no longer pulls them down.
+    el.scrollTop = 100;
+    fireEvent.scroll(el);
+    Object.defineProperty(el, "scrollHeight", { configurable: true, value: 1400 });
+    act(() => resize?.());
+    expect(el.scrollTop).toBe(100);
+
+    // They send a message: back to the end, and it sticks again.
+    view.rerender(<ConversationView sessionId="s1" fill live follow={1} />);
+    expect(el.scrollTop).toBe(1400);
+    Object.defineProperty(el, "scrollHeight", { configurable: true, value: 1600 });
+    act(() => resize?.());
+    expect(el.scrollTop).toBe(1600);
+  });
+});

client/src/components/conversation/__tests__/ConversationView.notYet.test.tsx

@@ -0,0 +1,37 @@
+/**
+ * @file ConversationView.notYet.test.tsx
+ * @description A live pane's new session has no row until its first hook:
+ * its 404 shows an empty chat, not "Session not found"; a replay still shows it.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { ConversationView } from "../ConversationView";
+
+const transcript = vi.hoisted(() =>
+  vi.fn(async () => {
+    throw Object.assign(new Error("Session not found"), { code: "NOT_FOUND", status: 404 });
+  })
+);
+vi.mock("../../../lib/api", async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    api: { sessions: { transcripts: vi.fn(async () => ({ transcripts: [] })), transcript } },
+  };
+});
+
+describe("ConversationView before a session's first hook", () => {
+  it("shows no error for a live pane", async () => {
+    render(<ConversationView sessionId="new" fill live />);
+    await waitFor(() => expect(transcript).toHaveBeenCalled());
+    await new Promise((r) => setTimeout(r, 0));
+    expect(screen.queryByText("Session not found")).toBeNull();
+  });
+
+  it("still reports it when not live", async () => {
+    render(<ConversationView sessionId="gone" fill />);
+    expect(await screen.findByText("Session not found")).toBeTruthy();
+  });
+});

client/src/components/conversation/__tests__/MarkdownContent.test.tsx

@@ -66,6 +66,43 @@ describe("<MarkdownContent />", () => {
     expect(screen.getByText("just a normal sentence.")).toBeInTheDocument();
   });
 
+  it("highlights standalone numbers, never ones inside a word, sha or issue ref", () => {
+    const { container } = render(
+      <MarkdownContent
+        text={"Took 3.5s, 87% done, $1.20, v2.7.1 on 2026-10-12 — abc123 file.2 #67 2fd0c903 x9"}
+      />
+    );
+    const nums = [...container.querySelectorAll("span.tabular-nums")].map((n) => n.textContent);
+    expect(nums).toEqual(["3.5s", "87%", "$1.20", "v2.7.1", "2026-10-12"]);
+  });
+
+  it("highlights an ISO date-time as one number", () => {
+    const { container } = render(
+      <MarkdownContent
+        text={"At 2026-10-12T08:00, 2026-10-12T08:00:00Z and 2026-10-12T08:00:00.123+07:00."}
+      />
+    );
+    const nums = [...container.querySelectorAll("span.tabular-nums")].map((n) => n.textContent);
+    expect(nums).toEqual([
+      "2026-10-12T08:00",
+      "2026-10-12T08:00:00Z",
+      "2026-10-12T08:00:00.123+07:00",
+    ]);
+  });
+
+  it("does not highlight numbers inside inline code", () => {
+    const { container } = render(<MarkdownContent text={"Run `sleep 5` now"} />);
+    expect(container.querySelector("span.tabular-nums")).toBeNull();
+  });
+
+  it("colours a flag label by how serious it is", () => {
+    render(<MarkdownContent text={"Lưu ý: a. Warning: b. Lỗi: c. Note that x"} />);
+    expect(screen.getByText("Lưu ý:").className).toContain("text-accent");
+    expect(screen.getByText("Warning:").className).toContain("text-status-warning");
+    expect(screen.getByText("Lỗi:").className).toContain("text-status-danger");
+    expect(screen.queryByText("Note")).toBeNull();
+  });
+
   it("handles empty input safely", () => {
     const { container } = render(<MarkdownContent text="" />);
     // Wrapper exists but no block elements

client/src/components/conversation/__tests__/MessageList.edits.test.tsx

@@ -0,0 +1,103 @@
+/**
+ * @file MessageList.edits.test.tsx
+ * @description Each assistant turn that changed files ends with Claude
+ * Desktop's "Edited N files" card: one row per file with the lines added and
+ * removed summed over the turn, a failed call left out, a row click handed
+ * to the caller, and a row (or the header, every file) dragged as `@path`
+ * attachments for a prompt box.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { describe, it, expect, vi } from "vitest";
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { MessageList } from "../MessageList";
+import type { TranscriptMessage } from "../../../lib/types";
+
+const at = "2026-10-09T08:00:00.000Z";
+const user = (text: string): TranscriptMessage =>
+  ({
+    type: "user",
+    sender: "user",
+    timestamp: at,
+    content: [{ type: "text", text }],
+  }) as TranscriptMessage;
+const call = (id: string, name: string, file_path: string): TranscriptMessage =>
+  ({
+    type: "assistant",
+    sender: "assistant",
+    timestamp: at,
+    content: [{ type: "tool_use", id, name, input: { file_path } }],
+  }) as TranscriptMessage;
+const result = (id: string, diff?: { added: number; removed: number }, is_error = false) =>
+  ({
+    type: "user",
+    sender: "tool",
+    timestamp: at,
+    content: [{ type: "tool_result", id, output: "ok", is_error, ...(diff ? { diff } : {}) }],
+  }) as TranscriptMessage;
+
+describe("the Edited N files card", () => {
+  it("sums each file's lines over the turn and opens a file on click", () => {
+    const onOpenFile = vi.fn();
+    render(
+      <MessageList
+        loading={false}
+        onOpenFile={onOpenFile}
+        messages={[
+          user("fix it"),
+          call("1", "Edit", "/w/a.ts"),
+          result("1", { added: 3, removed: 1 }),
+          call("2", "Write", "/w/b.md"),
+          result("2", { added: 10, removed: 0 }),
+          call("3", "Edit", "/w/a.ts"),
+          result("3", { added: 2, removed: 2 }),
+          call("4", "Edit", "/w/c.ts"),
+          result("4", undefined, true),
+          user("thanks"),
+          call("5", "Read", "/w/a.ts"),
+          result("5"),
+        ]}
+      />
+    );
+    const cards = screen.getAllByTestId("edited-files");
+    expect(cards).toHaveLength(1); // the second turn only read
+    const card = cards[0]!;
+    expect(within(card).getByText("Edited 2 files")).toBeTruthy();
+    expect(within(card).getByText("+15")).toBeTruthy();
+    expect(within(card).getByText("+5")).toBeTruthy(); // a.ts: 3+2 added
+    expect(within(card).queryByText("c.ts")).toBeNull(); // failed
+    fireEvent.click(within(card).getByTitle("/w/b.md"));
+    expect(onOpenFile).toHaveBeenCalledWith("/w/b.md");
+  });
+
+  it("drags a row as its @path attachment, and the header as every file", () => {
+    render(
+      <MessageList
+        loading={false}
+        messages={[
+          user("fix it"),
+          call("1", "Edit", "/w/a.ts"),
+          result("1", { added: 1, removed: 0 }),
+          call("2", "Write", "/w/b.md"),
+          result("2", { added: 2, removed: 0 }),
+        ]}
+      />
+    );
+    const card = screen.getByTestId("edited-files");
+    const drag = (el: Element) => {
+      const data: Record<string, string> = {};
+      fireEvent.dragStart(el, {
+        dataTransfer: { setData: (k: string, v: string) => (data[k] = v), effectAllowed: "" },
+      });
+      return data;
+    };
+    const one = drag(within(card).getByTitle("/w/b.md"));
+    expect(JSON.parse(one["application/x-agenthub-attach"]!)).toEqual([
+      { path: "@/w/b.md", name: "b.md" },
+    ]);
+    expect(one["text/plain"]).toBe("/w/b.md");
+    const all = drag(within(card).getByText("Edited 2 files"));
+    expect(
+      JSON.parse(all["application/x-agenthub-attach"]!).map((a: { path: string }) => a.path)
+    ).toEqual(["@/w/a.ts", "@/w/b.md"]);
+  });
+});

client/src/components/conversation/__tests__/MessageList.images.test.tsx

@@ -0,0 +1,113 @@
+/**
+ * @file MessageList.images.test.tsx
+ * @description An image the prompt box attached reaches the transcript as its
+ * saved drop path; the user's turn shows the image (served by
+ * `GET /api/run/drop/:name`), opens it full size on the page, and keeps any
+ * other path as typed. Claude Code turns a pasted drop path into an image
+ * block plus an `[Image: source: <path>]` meta line: the image joins the turn.
+ * URLs and absolute paths in a turn are links.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { describe, it, expect } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { MessageList, splitDropImages } from "../MessageList";
+import type { TranscriptMessage } from "../../../lib/types";
+
+const SHOT = "366d0a87d12176a2-image.png";
+
+describe("dropped images in a user turn", () => {
+  it("splitDropImages takes drop-dir image paths out of the text", () => {
+    expect(
+      splitDropImages(`Đây là cli và version đã có. /tmp/agenthub-drops-1001/${SHOT}`)
+    ).toEqual({ text: "Đây là cli và version đã có.", images: [SHOT] });
+    // Windows' temp dir, no prefix name.
+    expect(splitDropImages("C:\\Temp\\agenthub-drops--1\\0123456789abcdef.webp").images).toEqual([
+      "0123456789abcdef.webp",
+    ]);
+    // The drop dir since the data-dir move.
+    expect(splitDropImages(`[Image #1]fix this /home/me/.claude/agenthub/drops/${SHOT}`)).toEqual({
+      text: "fix this",
+      images: [SHOT],
+    });
+    // Not a drop, or not an image: left as typed.
+    for (const text of [
+      "/home/me/shot.png",
+      "/tmp/agenthub-drops-1001/0123456789abcdef-spec.pdf",
+    ]) {
+      expect(splitDropImages(text)).toEqual({ text, images: [] });
+    }
+  });
+
+  it("shows the image instead of its path, full size on click", () => {
+    const messages = [
+      {
+        type: "user",
+        sender: "user",
+        timestamp: "2026-10-09T08:00:00.000Z",
+        content: [{ type: "text", text: `look at this /tmp/agenthub-drops-1001/${SHOT}` }],
+      },
+    ] as TranscriptMessage[];
+    render(<MessageList messages={messages} loading={false} />);
+
+    const bubble = screen.getByTestId("chat-user");
+    expect(bubble).toHaveTextContent("look at this");
+    expect(bubble).not.toHaveTextContent("agenthub-drops");
+    const img = screen.getByRole("img", { name: SHOT });
+    expect(img.getAttribute("src")).toBe(`/api/run/drop/${SHOT}`);
+
+    fireEvent.click(img);
+    expect(screen.getByTestId("image-lightbox").parentElement).toBe(document.body);
+  });
+
+  it("folds Claude Code's [Image: source:] meta line into the turn", () => {
+    const messages = [
+      {
+        type: "user",
+        sender: "user",
+        timestamp: "2026-10-09T09:43:00.000Z",
+        content: [{ type: "text", text: "[Image #1]Hãy giúp tôi fix lỗi" }],
+      },
+      {
+        type: "user",
+        sender: "system",
+        timestamp: "2026-10-09T09:43:11.000Z",
+        content: [
+          { type: "text", text: `[Image: source: /home/me/.claude/agenthub/drops/${SHOT}]` },
+        ],
+      },
+    ] as TranscriptMessage[];
+    render(<MessageList messages={messages} loading={false} />);
+
+    expect(screen.queryByText("System")).toBeNull();
+    const bubble = screen.getByTestId("chat-user");
+    expect(bubble).toHaveTextContent("Hãy giúp tôi fix lỗi");
+    expect(bubble).not.toHaveTextContent("[Image #1]");
+    expect(screen.getByRole("img", { name: SHOT }).getAttribute("src")).toBe(
+      `/api/run/drop/${SHOT}`
+    );
+  });
+
+  it("makes URLs and absolute paths clickable", () => {
+    const opened: string[] = [];
+    const messages = [
+      {
+        type: "user",
+        sender: "user",
+        timestamp: "2026-10-09T09:43:00.000Z",
+        content: [
+          {
+            type: "text",
+            text: "xem (https://git.example.com/a/issues/69) và /home/me/repo/server/x.js.",
+          },
+        ],
+      },
+    ] as TranscriptMessage[];
+    render(<MessageList messages={messages} loading={false} onOpenFile={(p) => opened.push(p)} />);
+
+    const link = screen.getByRole("link", { name: "https://git.example.com/a/issues/69" });
+    expect(link.getAttribute("href")).toBe("https://git.example.com/a/issues/69");
+    expect(link.getAttribute("target")).toBe("_blank");
+    fireEvent.click(screen.getByRole("button", { name: "/home/me/repo/server/x.js" }));
+    expect(opened).toEqual(["/home/me/repo/server/x.js"]);
+  });
+});

client/src/components/conversation/__tests__/MessageList.sender.test.tsx

@@ -1,13 +1,16 @@
 /**
  * @file MessageList.sender.test.tsx
- * @description Verifies the transcript renders each message under its TRUE
- * sender label — User / Assistant / Main agent / System — instead of labeling
- * every `type:"user"` line "User" (reported transcript mis-attribution).
+ * @description Verifies the transcript renders each message by its TRUE
+ * sender — the human as a bubble, the assistant's prose bare (Claude Desktop's
+ * layout), Main agent / System under their own label — instead of treating
+ * every `type:"user"` line as the user (reported transcript mis-attribution) —
+ * and folds a run of tool calls into one line; a typed `/command` or `@path`
+ * shows as a chip.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 import { describe, it, expect } from "vitest";
-import { render, screen } from "@testing-library/react";
-import { MessageList } from "../MessageList";
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { MessageList, workLabel, workingOn } from "../MessageList";
 import type { TranscriptMessage } from "../../../lib/types";
 
 function msg(partial: Partial<TranscriptMessage>): TranscriptMessage {
@@ -20,6 +23,21 @@ function msg(partial: Partial<TranscriptMessage>): TranscriptMessage {
 }
 
 describe("MessageList — sender attribution", () => {
+  it("shows a typed /command and @path as chips in the user's bubble", () => {
+    render(
+      <MessageList
+        messages={[
+          msg({ sender: "user", content: [{ type: "text", text: "/review @src/a.ts now" }] }),
+        ]}
+        loading={false}
+      />
+    );
+    const bubble = screen.getByTestId("chat-user");
+    expect(bubble).toHaveTextContent("/review @src/a.ts now");
+    expect(within(bubble).getByText("/review").className).toContain("text-accent");
+    expect(within(bubble).getByText("@src/a.ts").className).toContain("text-violet");
+  });
+
   it("labels each row by its sender, not blanket 'User'", () => {
     const messages: TranscriptMessage[] = [
       msg({ sender: "user", content: [{ type: "text", text: "spin up a team" }] }),
@@ -36,8 +54,8 @@ describe("MessageList — sender attribution", () => {
     ];
     render(<MessageList messages={messages} loading={false} />);
 
-    expect(screen.getByText("User")).toBeInTheDocument();
-    expect(screen.getByText("Assistant")).toBeInTheDocument();
+    expect(screen.getByTestId("chat-user")).toHaveTextContent("spin up a team");
+    expect(screen.getByTestId("chat-assistant")).toHaveTextContent("on it");
     expect(screen.getByText("System")).toBeInTheDocument();
     expect(screen.getByText("Main agent")).toBeInTheDocument();
   });
@@ -48,7 +66,158 @@ describe("MessageList — sender attribution", () => {
       msg({ type: "assistant", content: [{ type: "text", text: "hello" }] }), // → "Assistant"
     ];
     render(<MessageList messages={messages} loading={false} />);
-    expect(screen.getByText("User")).toBeInTheDocument();
-    expect(screen.getByText("Assistant")).toBeInTheDocument();
+    expect(screen.getByTestId("chat-user")).toHaveTextContent("hi there");
+    expect(screen.getByTestId("chat-assistant")).toHaveTextContent("hello");
+  });
+
+  it("folds consecutive tool calls — one per transcript line — into one line", () => {
+    const call = (id: string) =>
+      msg({
+        type: "assistant",
+        sender: "assistant",
+        content: [{ type: "tool_use", id, name: "Bash", input: { command: `echo ${id}` } }],
+      });
+    const result = (id: string) => msg({ content: [{ type: "tool_result", id, output: "ok" }] });
+    const messages = [call("a"), result("a"), call("b"), result("b"), call("c")];
+    render(<MessageList messages={messages} loading={false} />);
+    const group = screen.getAllByTestId("chat-tools");
+    expect(group).toHaveLength(1);
+    fireEvent.click(screen.getByRole("button", { name: /Ran 3 commands/ }));
+    expect(group[0]).toHaveTextContent("echo b");
+  });
+
+  it("names a mixed run by what it did, like Claude Desktop", () => {
+    const use = (name: string) => ({ type: "tool_use" as const, name });
+    expect(workLabel([use("Bash"), use("Bash"), use("Edit"), use("Read")])).toBe(
+      "Ran 2 commands, edited a file, read a file"
+    );
+    expect(workLabel([{ type: "thinking", text: "hm" }])).toBe("Thinking");
+    // Desktop's fixed order, whatever ran first: other tools always last.
+    expect(workLabel([use("mcp__x__y"), use("Read"), use("Bash")])).toBe(
+      "Ran 1 command, read a file, used a tool"
+    );
+  });
+
+  it("reads a thinking block's text as narration, between two groups", () => {
+    const call = (id: string) =>
+      msg({
+        type: "assistant",
+        sender: "assistant",
+        content: [{ type: "tool_use", id, name: "Bash", input: { command: `echo ${id}` } }],
+      });
+    const result = (id: string) => msg({ content: [{ type: "tool_result", id, output: "ok" }] });
+    const say = (text: string) =>
+      msg({ type: "assistant", sender: "assistant", content: [{ type: "thinking", text }] });
+    render(
+      <MessageList
+        loading={false}
+        messages={[call("a"), result("a"), say("Found an issue."), say(""), call("b"), result("b")]}
+      />
+    );
+    expect(screen.getAllByTestId("chat-tools")).toHaveLength(2);
+    expect(screen.getByText("Found an issue.")).toBeTruthy();
+  });
+
+  it("shows the whole prompt as ↓, not just its uncached tail", () => {
+    render(
+      <MessageList
+        loading={false}
+        messages={[
+          msg({
+            type: "assistant",
+            sender: "assistant",
+            content: [{ type: "text", text: "done" }],
+            usage: {
+              input_tokens: 2,
+              output_tokens: 40,
+              cache_read_input_tokens: 120000,
+              cache_creation_input_tokens: 3000,
+            },
+          }),
+        ]}
+      />
+    );
+    expect(screen.getByText(/↓ 123/)).toBeTruthy();
+  });
+
+  it("ends a live chat with the step still running", () => {
+    const messages = [
+      msg({ type: "user", sender: "user", content: [{ type: "text", text: "test it" }] }),
+      msg({
+        type: "assistant",
+        sender: "assistant",
+        timestamp: new Date(Date.now() - 65_000).toISOString(),
+        content: [
+          {
+            type: "tool_use",
+            id: "t1",
+            name: "Bash",
+            input: { command: "npm test", description: "Run the full client suite" },
+          },
+        ],
+      }),
+    ];
+    const { rerender } = render(<MessageList loading={false} messages={messages} live />);
+    const row = screen.getByTestId("chat-running-step");
+    expect(row).toHaveTextContent("Run the full client suite");
+    expect(row).toHaveTextContent(/1m \ds/);
+    // Its result arrived: nothing is running any more.
+    rerender(
+      <MessageList
+        loading={false}
+        live
+        messages={[
+          ...messages,
+          msg({ content: [{ type: "tool_result", id: "t1", output: "ok" }] }),
+        ]}
+      />
+    );
+    expect(screen.queryByTestId("chat-running-step")).toBeNull();
+  });
+
+  it("knows what a live turn is doing until it ends", () => {
+    const now = Date.parse("2026-06-26T08:20:00.000Z");
+    const at = "2026-06-26T08:19:00.000Z";
+    const prompt = msg({ type: "user", sender: "user", timestamp: at });
+    const call = msg({
+      type: "assistant",
+      sender: "assistant",
+      timestamp: at,
+      stop_reason: "tool_use",
+      content: [{ type: "tool_use", id: "t1", name: "Bash", input: { command: "ls" } }],
+    });
+    const result = msg({
+      sender: "tool",
+      timestamp: at,
+      content: [{ type: "tool_result", id: "t1", output: "ok" }],
+    });
+    const reply = (stop_reason?: string) =>
+      msg({
+        type: "assistant",
+        sender: "assistant",
+        timestamp: at,
+        stop_reason,
+        content: [{ type: "text", text: "ok" }],
+      });
+    const results = (m: ReturnType<typeof msg>[]) =>
+      new Map(
+        m.flatMap((x) => x.content.filter((c) => c.type === "tool_result").map((c) => [c.id!, c]))
+      );
+    const state = (m: ReturnType<typeof msg>[]) => workingOn(m, results(m), now);
+
+    expect(state([prompt])).toEqual({ block: null, since: at }); // thinking on the prompt
+    expect(state([prompt, call])?.block?.id).toBe("t1"); // the call is running
+    expect(state([prompt, call, result])).toEqual({ block: null, since: at }); // thinking again
+    expect(state([prompt, call, result, reply("tool_use")])?.block).toBeNull(); // narration, a call follows
+    expect(state([prompt, call, result, reply("end_turn")])).toBeNull(); // turn over
+    expect(state([prompt, call, result, reply()])).toBeNull(); // an older server: no stop_reason
+    const stopped = msg({
+      type: "user",
+      sender: "user",
+      content: [{ type: "text", text: "[Request interrupted by user]" }],
+    });
+    expect(state([prompt, call, result, stopped])).toBeNull();
+    // Silent for 15 minutes with nothing running: the turn died.
+    expect(workingOn([prompt], new Map(), now + 20 * 60_000)).toBeNull();
   });
 });

client/src/components/lanes/AddLaneModal.tsx

@@ -1,7 +1,8 @@
 /**
  * @file AddLaneModal.tsx
  * @description The "+ Add lane" flow, in one of two modes chosen with a
- * segmented toggle: "Repo" adopts an existing directory as-is via
+ * segmented toggle — "Repo" by default; a branch prefill (the git bar's "new
+ * workspace from this branch") opens on "Worktree": "Repo" adopts an existing directory as-is via
  * `POST /api/lanes/ensure` (no worktree, no branch — the right mode for a
  * main repo you want stage detection on); "Worktree" provisions a
  * dashboard-managed git worktree via `POST /api/lanes/worktree` with a
@@ -9,7 +10,8 @@
  * (Claude Code or Codex) — this choice is immutable after creation. Either
  * mode's path field can be filled by typing, by the CwdAutocomplete
  * suggestions, or by Browse (`PathPickButton`: the OS's own folder picker
- * opened by the server, the in-app `FolderBrowseModal` where it cannot be).
+ * opened by the server, the in-app `FolderBrowseModal` where it cannot be) —
+ * which a click into the field opens too.
  * The worktree lane returned is `status: "provisioning"`:
  * the route answers before the actual `git worktree add` runs, so this
  * component polls `GET /api/lanes/:id` until that finishes before running the
@@ -28,6 +30,7 @@ import type { CwdSuggestion } from "../../lib/api";
 import type { Lane, LaneWorktree } from "../../lib/types";
 import { useAiTools } from "../../hooks/useAiTools";
 import { AiToolIcon } from "../AiToolIcon";
+import { readDefaultTool } from "../../lib/sessionDefaults";
 
 /** Polls the lane until the background `git worktree add` finishes (status
  *  leaves "provisioning"), or gives up after `timeoutMs`. Returns the final
@@ -94,7 +97,7 @@ export function AddLaneModal({
   cwdSuggestions: CwdSuggestion[];
 }) {
   const { t } = useTranslation(["lanes"]);
-  const [mode, setMode] = useState<"repo" | "worktree">("worktree");
+  const [mode, setMode] = useState<"repo" | "worktree">("repo");
   const [sourceRepo, setSourceRepo] = useState("");
   const [title, setTitle] = useState("");
   const [branch, setBranch] = useState("");
@@ -110,7 +113,14 @@ export function AddLaneModal({
   // null = the default AI tool (Settings → AI Tools), resolved at submit time.
   const [pickedTool, setPickedTool] = useState<string | null>(null);
   const aiTools = useAiTools();
-  const defaultTool = aiTools.defaultId ?? "claude";
+  // The account's own pick (first-run setup), while it is installed and on.
+  const ownTool = readDefaultTool();
+  const defaultTool =
+    (ownTool && aiTools.tools.some((x) => x.id === ownTool && x.installed && x.enabled)
+      ? ownTool
+      : null) ??
+    aiTools.defaultId ??
+    "claude";
   const tool = pickedTool ?? defaultTool;
   // Installed + enabled, the default first.
   const toolChoices = aiTools.tools
@@ -130,7 +140,7 @@ export function AddLaneModal({
   } | null>(null);
 
   const reset = () => {
-    setMode("worktree");
+    setMode("repo");
     setSourceRepo("");
     setTitle("");
     setBranch("");
@@ -151,6 +161,8 @@ export function AddLaneModal({
     if (!open || !prefill) return;
     if (prefill.sourceRepo) setSourceRepo(prefill.sourceRepo);
     if (prefill.branch) {
+      // A branch only means something to a worktree.
+      setMode("worktree");
       setBranch(prefill.branch);
       setBranchMode("existing");
     }
@@ -316,6 +328,7 @@ export function AddLaneModal({
   const titleId = useId();
   const panelRef = useRef<HTMLDivElement>(null);
   const cancelRef = useRef<HTMLButtonElement>(null);
+  const browseRef = useRef<HTMLButtonElement>(null);
   useDialog(open, panelRef, handleCancel, cancelRef);
 
   // A summary on screen means the lane already exists and a step failed, so
@@ -352,6 +365,7 @@ export function AddLaneModal({
         role="dialog"
         aria-modal="true"
         aria-labelledby={titleId}
+        data-tour="add-lane"
       >
         <div className="flex items-center gap-3 border-b border-border px-5 py-3.5">
           <h3 id={titleId} className="min-w-0 flex-1 text-sm font-semibold text-fg-primary">
@@ -446,8 +460,15 @@ export function AddLaneModal({
             <label className="mb-1 block text-xs text-fg-secondary" htmlFor="add-lane-repo">
               {mode === "repo" ? t("addLaneRepoLabelAdopt") : t("addLaneRepoLabel")}
             </label>
-            <div className="flex gap-1.5">
-              <div className="min-w-0 flex-1">
+            <div className="flex gap-1.5" data-tour="add-lane-folder">
+              {/* A click into the path opens the picker, as Browse does (the
+                OS's own where it can be); typing still works from the keyboard. */}
+              <div
+                className="min-w-0 flex-1"
+                onClick={(e) => {
+                  if ((e.target as HTMLElement).tagName === "INPUT") browseRef.current?.click();
+                }}
+              >
                 <CwdAutocomplete
                   inputId="add-lane-repo"
                   value={sourceRepo}
@@ -455,7 +476,12 @@ export function AddLaneModal({
                   suggestions={cwdSuggestions}
                 />
               </div>
-              <PathPickButton start={sourceRepo} onPick={setSourceRepo} showLabel />
+              <PathPickButton
+                start={sourceRepo}
+                onPick={setSourceRepo}
+                showLabel
+                buttonRef={browseRef}
+              />
             </div>
             <p className="mt-1 text-[10px] text-fg-muted">
               {mode === "repo" ? t("addLaneRepoHintAdopt") : t("addLaneRepoHint")}
@@ -692,6 +718,7 @@ export function AddLaneModal({
             type="button"
             onClick={done ? handleCancel : submit}
             disabled={busy || disabled}
+            data-tour="add-lane-create"
             className="btn-primary text-xs disabled:opacity-50"
           >
             {done ? t("addLaneSetupClose") : t("add")}

client/src/components/lanes/DiffEditor.tsx

@@ -3,7 +3,9 @@
  * file's original text (HEAD, or a branch's merge base), editable while the
  * diff re-colours as you type. `unified` is one editor with the removed lines
  * inline above their replacement (`unifiedMergeView`); `split` is the
- * original read-only on the left beside the editable file (`MergeView`).
+ * original read-only on the left beside the editable file, JetBrains-shaped —
+ * two scrollers kept on matching lines, no padding, a curved band per changed
+ * block between them (`splitDiff.ts`).
  * `collapse` folds unchanged stretches away — the panel's Changes view —
  * and every changed block carries a Revert that puts the original back in the
  * editor (nothing is written until Save). Green marks a line added whole, red
@@ -11,27 +13,55 @@
  * text), its edit in a stronger blue — the same scheme as the read-only diff in
  * LaneDiffView. Syntax colours come from the dashboard's own per-line
  * tokenizer (`lib/highlight.ts`), like every other code view here.
+ * Given `onBlock`, each changed block also gets the read-only diff's bar under
+ * its last line — Undo (asks twice) and the block's commit checkbox
+ * (`blockIncluded`) — in place of its Revert; the panel turns it off while
+ * the editor holds unsaved text, because git acts on the file on disk.
+ * Given `blame`, a gutter left of the line numbers names each line's last
+ * commit (Annotate); a click hands its sha to `onBlameClick`. `navRef` gets
+ * a function that moves the cursor to the next / previous changed block.
+ * Given `onAddToChat`, a selection in the editable file gets Cursor's Add to
+ * Chat chip floating above its last line, at the column where it ends,
+ * which hands the panel the selection's 1-based lines.
  * Lazy-loaded by LaneChangesPanel, which keys it by file and shape:
  * CodeMirror stays out of the main bundle, and one mount is one view.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 import { useEffect, useRef } from "react";
-import { EditorState, RangeSetBuilder } from "@codemirror/state";
+import { useTranslation } from "react-i18next";
+import {
+  Compartment,
+  EditorSelection,
+  EditorState,
+  RangeSetBuilder,
+  StateEffect,
+  StateField,
+  Text,
+} from "@codemirror/state";
 import {
   Decoration,
   EditorView,
   ViewPlugin,
+  WidgetType,
   drawSelection,
+  gutter,
+  GutterMarker,
   highlightActiveLine,
   highlightActiveLineGutter,
   keymap,
   lineNumbers,
+  showTooltip,
+  type Tooltip,
   type DecorationSet,
   type ViewUpdate,
 } from "@codemirror/view";
 import { defaultKeymap, history, historyKeymap, indentWithTab } from "@codemirror/commands";
-import { MergeView, getChunks, unifiedMergeView, type Chunk } from "@codemirror/merge";
+import { unifiedMergeView, type Chunk } from "@codemirror/merge";
+import { chunksOf, splitDiff } from "./splitDiff";
 import { highlight, tokenClass } from "../../lib/highlight";
+import type { LaneBlame } from "../../lib/types";
+
+type Blame = Extract<LaneBlame, { available: true }>;
 
 /**
  * True when a letter or digit of a line (`text`, starting at document offset
@@ -60,14 +90,14 @@ const mark = (cls: string) => {
  *  either side of a split view (`a` is the original). */
 function decorate(view: EditorView, lang: string): DecorationSet {
   const out = new RangeSetBuilder<Decoration>();
-  const info = getChunks(view.state);
+  const info = chunksOf(view.state);
   const a = info?.side === "a";
   const span = (k: Chunk) => (a ? [k.fromA, k.toA, k.endA] : [k.fromB, k.toB, k.endB]);
   const chunks = info?.chunks ?? [];
   const doc = view.state.doc;
   let last = 0;
   for (const { from, to } of view.visibleRanges) {
-    for (let pos = from; pos <= to; ) {
+    for (let pos = from; pos <= to;) {
       const line = doc.lineAt(pos);
       pos = line.to + 1;
       if (line.number <= last) continue;
@@ -139,6 +169,159 @@ const diffColours = (lang: string) =>
     { decorations: (p) => p.decorations }
   );
 
+/** A changed block by line (1-based; a count of 0 is a pure insertion or
+ *  removal): what the panel matches against git's own change blocks. */
+export type EditorBlock = { oldFrom: number; oldCount: number; newFrom: number; newCount: number };
+export type BlockAction = "include" | "undo";
+
+/** One Annotate cell: the line's commit date and author, its subject on hover. */
+class BlameMarker extends GutterMarker {
+  constructor(
+    readonly text: string,
+    readonly title: string
+  ) {
+    super();
+  }
+  override eq(other: BlameMarker) {
+    return other.text === this.text && other.title === this.title;
+  }
+  override toDOM() {
+    const el = document.createElement("span");
+    el.textContent = this.text;
+    el.title = this.title;
+    return el;
+  }
+}
+
+/** The Annotate gutter for the editable file's lines (the B side). ponytail:
+ *  lines are matched by number, so unsaved edits above a line shift its
+ *  annotation until the file is saved and re-annotated. */
+function blameGutter(blame: Blame, notCommitted: string, onClick: (sha: string) => void) {
+  const shaAt = (state: EditorState, pos: number) => blame.lines[state.doc.lineAt(pos).number - 1];
+  return gutter({
+    class: "cm-ah-blame",
+    lineMarker(view, line) {
+      const sha = shaAt(view.state, line.from);
+      if (sha === undefined) return null;
+      const c = sha ? blame.commits[sha] : undefined;
+      return c
+        ? new BlameMarker(`${c.date.slice(0, 10)} ${c.author}`, `${c.short} ${c.summary}`)
+        : new BlameMarker(notCommitted, notCommitted);
+    },
+    initialSpacer: () => new BlameMarker("0000-00-00 Author Name", ""),
+    domEventHandlers: {
+      mousedown(view, line) {
+        const sha = shaAt(view.state, line.from);
+        if (sha) onClick(sha);
+        return !!sha;
+      },
+    },
+  });
+}
+
+/** A chunk side's first line and line count. `to` is the start of the line
+ *  after the chunk (or the end + 1), so its last line holds `to - 1`. */
+const lineSpan = (doc: Text, from: number, to: number): [number, number] => {
+  const first = doc.lineAt(Math.min(from, doc.length)).number;
+  return [first, from >= to ? 0 : doc.lineAt(Math.min(to - 1, doc.length)).number - first + 1];
+};
+
+class BlockBar extends WidgetType {
+  constructor(
+    readonly block: EditorBlock,
+    readonly build: (b: EditorBlock) => HTMLElement
+  ) {
+    super();
+  }
+  eq(o: BlockBar) {
+    const a = this.block;
+    const b = o.block;
+    return (
+      a.oldFrom === b.oldFrom &&
+      a.oldCount === b.oldCount &&
+      a.newFrom === b.newFrom &&
+      a.newCount === b.newCount
+    );
+  }
+  toDOM() {
+    return this.build(this.block);
+  }
+}
+
+const barsOn = StateEffect.define<boolean>();
+
+/** One bar per chunk, under its last line (above a pure removal), rebuilt
+ *  whenever the chunks are — and dropped while `barsOn` is false. */
+function blockBars(orig: Text, build: (b: EditorBlock) => HTMLElement) {
+  const decos = (doc: Text, chunks: readonly Chunk[]) => {
+    const out = new RangeSetBuilder<Decoration>();
+    for (const c of chunks) {
+      const [oldFrom, oldCount] = lineSpan(orig, c.fromA, c.toA);
+      const [newFrom, newCount] = lineSpan(doc, c.fromB, c.toB);
+      const pos = newCount ? doc.line(newFrom + newCount - 1).to : Math.min(c.fromB, doc.length);
+      out.add(
+        pos,
+        pos,
+        Decoration.widget({
+          block: true,
+          side: newCount ? 1 : -1,
+          widget: new BlockBar({ oldFrom, oldCount, newFrom, newCount }, build),
+        })
+      );
+    }
+    return out.finish();
+  };
+  return StateField.define<{ on: boolean; deco: DecorationSet }>({
+    create: () => ({ on: false, deco: Decoration.none }),
+    update(v, tr) {
+      let on = v.on;
+      for (const e of tr.effects) if (e.is(barsOn)) on = e.value;
+      const chunks = chunksOf(tr.state)?.chunks;
+      if (on === v.on && chunks === chunksOf(tr.startState)?.chunks) {
+        return tr.docChanged ? { on, deco: v.deco.map(tr.changes) } : v;
+      }
+      return { on, deco: on && chunks ? decos(tr.state.doc, chunks) : Decoration.none };
+    },
+    provide: (f) => EditorView.decorations.from(f, (v) => v.deco),
+  });
+}
+
+/** Add to Chat floating just above the selection's last line, at the column
+ *  where the selection ends — so a long line never pushes it out of view.
+ *  `build` makes its DOM from the selection's first and last 1-based line. A
+ *  selection ending at a line's start (a whole-line drag) does not take that
+ *  line, and the chip then sits at the start of the last line it does take. */
+function chatChip(build: (start: number, end: number) => HTMLElement) {
+  return StateField.define<Tooltip | null>({
+    create: () => null,
+    update(tip, tr) {
+      if (!tr.docChanged && !tr.selection) return tip;
+      const { from, to, empty } = tr.state.selection.main;
+      if (empty) return null;
+      const doc = tr.state.doc;
+      const first = doc.lineAt(from);
+      const last = doc.lineAt(to);
+      const wholeLine = to === last.from && last.number > first.number;
+      const end = wholeLine ? last.number - 1 : last.number;
+      return {
+        pos: wholeLine ? doc.line(end).from : to,
+        above: true,
+        create: () => {
+          const dom = build(first.number, end);
+          dom.classList.add("cm-chat-chip");
+          return { dom };
+        },
+      };
+    },
+    provide: (f) => showTooltip.from(f),
+  });
+}
+
+const CHIP = "flex shrink-0 items-center gap-0.5 rounded border px-1 leading-[14px] cursor-pointer";
+const UNDO =
+  "border-border-light text-fg-secondary hover:border-status-danger/60 hover:text-status-danger";
+const UNDO_ARMED = "border-status-danger bg-status-danger/20 text-status-danger";
+
 const GREEN = "rgb(var(--status-success) / 0.18)";
 const RED = "rgb(var(--status-danger) / 0.18)";
 const BLUE = "rgb(var(--diff-mod) / 0.18)";
@@ -167,9 +350,19 @@ const theme = EditorView.theme({
   ".cm-activeLine": { backgroundColor: "rgb(var(--fg-primary) / 0.04)" },
   ".cm-activeLineGutter": { backgroundColor: "rgb(var(--fg-primary) / 0.08)" },
   ".cm-cursor": { borderLeftColor: "rgb(var(--fg-primary))" },
-  "&.cm-focused .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection": {
-    backgroundColor: "rgb(var(--accent) / 0.3)",
+  // Doubled classes: drawSelection's base theme scopes its light/dark colours
+  // as `.ͼ1.ͼ2.cm-focused > .cm-scroller > .cm-selectionLayer …`, which a
+  // plain `.cm-selectionBackground` never outranks.
+  "&.cm-focused.cm-focused > .cm-scroller > .cm-selectionLayer .cm-selectionBackground, .cm-selectionLayer .cm-selectionBackground.cm-selectionBackground, .cm-content ::selection":
+    {
+      background: "rgb(var(--accent) / 0.3)",
+    },
+  // Doubled class: outranks the base theme's light/dark-scoped tooltip frame.
+  ".cm-tooltip.cm-chat-chip.cm-chat-chip": {
+    border: "1px solid rgb(var(--accent) / 0.6)",
+    backgroundColor: "rgb(var(--surface-1))",
   },
+  ".cm-tooltip.cm-chat-chip.cm-chat-chip:hover": { backgroundColor: "rgb(var(--surface-2))" },
   [`${M} .cm-changedLine`]: { backgroundColor: GREEN },
   [`${M} .cm-changedLine.cm-ah-mod`]: { backgroundColor: BLUE },
   [`${M} .cm-changedText`]: { background: "none" },
@@ -192,14 +385,21 @@ const theme = EditorView.theme({
     background: "rgb(var(--surface-2))",
   },
   ".cm-chunkButtons": { zIndex: "1" },
+  ".cm-ah-blame .cm-gutterElement": {
+    color: "rgb(var(--fg-muted))",
+    cursor: "pointer",
+    fontSize: "10px",
+    paddingRight: "6px",
+    whiteSpace: "nowrap",
+  },
 });
 
-/** The Revert button on a changed block; @codemirror/merge wires the click.
- *  Between split columns there is room for an arrow only (`→`: left onto right). */
-function revertButton(label: string, arrow = false) {
+/** The Revert button on a changed block (unified); @codemirror/merge wires
+ *  the click. The split layout draws its own » in the gutter. */
+function revertButton(label: string) {
   const b = document.createElement("button");
   b.type = "button";
-  b.textContent = arrow ? "→" : label;
+  b.textContent = label;
   b.title = label;
   b.setAttribute("aria-label", label);
   b.className =
@@ -217,6 +417,12 @@ export default function DiffEditor({
   revertLabel,
   onChange,
   onSave,
+  onBlock,
+  blockIncluded,
+  blame,
+  onBlameClick,
+  navRef,
+  onAddToChat,
 }: {
   value: string;
   /** The text the diff is taken against; read once, at mount. */
@@ -231,15 +437,85 @@ export default function DiffEditor({
   revertLabel: string;
   onChange: (text: string) => void;
   onSave: () => void;
+  /** Undo one changed block in git, or flip its commit checkbox; absent = no bars. */
+  onBlock?: (action: BlockAction, block: EditorBlock) => void;
+  /** Whether a block is ticked for the commit (its checkbox's state). */
+  blockIncluded?: (block: EditorBlock) => boolean;
+  /** Annotate: each line's last commit; absent = no gutter. */
+  blame?: Blame;
+  onBlameClick?: (sha: string) => void;
+  /** Set to "go to the next (1) / previous (-1) changed block". */
+  navRef?: { current: ((dir: 1 | -1) => void) | null };
+  /** Add the selected lines (1-based, inclusive) to the chat; absent = no chip. */
+  onAddToChat?: (start: number, end: number) => void;
 }) {
+  const { t } = useTranslation("lanes");
   const host = useRef<HTMLDivElement>(null);
   const view = useRef<EditorView | null>(null);
-  const cb = useRef({ onChange, onSave });
-  cb.current = { onChange, onSave };
+  const cb = useRef({ onChange, onSave, onBlock, blockIncluded, onBlameClick, onAddToChat, t });
+  cb.current = { onChange, onSave, onBlock, blockIncluded, onBlameClick, onAddToChat, t };
+  const blameSlot = useRef(new Compartment()).current;
+
+  /** The diff view's review bar, as DOM: pinned to the visible right edge,
+   *  zero height so it never pushes lines (or a split view's alignment). */
+  const buildBar = (block: EditorBlock) => {
+    const tr = cb.current.t;
+    const wrap = document.createElement("div");
+    wrap.className = "flex h-0";
+    const pin = wrap.appendChild(document.createElement("span"));
+    pin.className = "sticky right-2 ml-auto h-0 w-0 self-start";
+    const bar = pin.appendChild(document.createElement("span"));
+    bar.dataset.testid = "lane-editor-block-bar";
+    bar.className =
+      "absolute right-0 top-0.5 z-10 flex items-center gap-1 whitespace-nowrap rounded border border-border-light bg-surface-1 px-1 py-0.5 font-sans text-[10px] leading-[14px] text-fg-secondary shadow-card";
+    const chip = (text: string, title: string, cls: string) => {
+      const b = bar.appendChild(document.createElement("button"));
+      b.type = "button";
+      b.textContent = text;
+      b.title = title;
+      b.setAttribute("aria-label", title);
+      b.className = `${CHIP} ${cls}`;
+      return b;
+    };
+    const undo = chip(tr("changes.undoHunkShort"), tr("changes.undoHunk"), UNDO);
+    // The block's commit checkbox, a real one so it reads like the diff's.
+    const include = bar.appendChild(document.createElement("input"));
+    include.type = "checkbox";
+    include.checked = cb.current.blockIncluded?.(block) ?? true;
+    include.title = tr("changes.includeBlock");
+    include.setAttribute("aria-label", tr("changes.includeBlock"));
+    include.className = "h-3 w-3 cursor-pointer";
+    // Two clicks, like every undo git cannot give back; disarms after 3 s.
+    let timer = 0;
+    const arm = (on: boolean) => {
+      undo.dataset.armed = on ? "1" : "";
+      undo.textContent = tr(on ? "changes.undoHunkShortConfirm" : "changes.undoHunkShort");
+      const title = tr(on ? "changes.undoHunkConfirm" : "changes.undoHunk");
+      undo.title = title;
+      undo.setAttribute("aria-label", title);
+      undo.className = `${CHIP} ${on ? UNDO_ARMED : UNDO}`;
+    };
+    undo.onclick = () => {
+      window.clearTimeout(timer);
+      if (undo.dataset.armed) {
+        arm(false);
+        cb.current.onBlock?.("undo", block);
+        return;
+      }
+      arm(true);
+      timer = window.setTimeout(() => arm(false), 3000);
+    };
+    include.onchange = () => cb.current.onBlock?.("include", block);
+    return wrap;
+  };
 
   useEffect(() => {
     const folded = collapse ? { margin: 3, minSize: 4 } : undefined;
-    const common = [lineNumbers(), diffColours(lang), theme];
+    // A CRLF file stays CRLF: CodeMirror would hand `onChange` LF text, the
+    // panel would read that as an unsaved edit (no Undo / Keep bars) and Save
+    // would rewrite every line ending.
+    const eol = value.includes("\r\n") ? [EditorState.lineSeparator.of("\r\n")] : [];
+    const common = [lineNumbers(), diffColours(lang), theme, ...eol];
     const editing = [
       ...common,
       highlightActiveLineGutter(),
@@ -261,25 +537,41 @@ export default function DiffEditor({
       ]),
       EditorView.contentAttributes.of({ "aria-label": label }),
       EditorView.updateListener.of((u) => {
-        if (u.docChanged) cb.current.onChange(u.state.doc.toString());
+        if (u.docChanged) cb.current.onChange(u.state.sliceDoc());
       }),
+      blockBars(Text.of(original.split(/\r?\n/)), buildBar),
+      blameSlot.of([]),
+      ...(onAddToChat
+        ? [
+            chatChip((start, end) => {
+              const b = document.createElement("button");
+              b.type = "button";
+              b.dataset.testid = "lane-editor-add-to-chat";
+              b.textContent = cb.current.t("changes.addToChat");
+              b.className =
+                "rounded border border-accent/60 bg-surface-1 px-1.5 font-sans text-[10px] leading-[14px] text-accent hover:bg-surface-2";
+              // Keep the editor's focus (and so its selection) through the click.
+              b.onmousedown = (e) => e.preventDefault();
+              b.onclick = () => cb.current.onAddToChat?.(start, end);
+              return b;
+            }),
+          ]
+        : []),
     ];
     let v: EditorView;
     let destroy: () => void;
     if (layout === "split") {
-      const mv = new MergeView({
+      const sd = splitDiff({
         parent: host.current!,
-        a: {
-          doc: original,
-          extensions: [...common, EditorState.readOnly.of(true), EditorView.editable.of(false)],
-        },
-        b: { doc: value, extensions: editing },
-        revertControls: "a-to-b",
-        renderRevertControl: () => revertButton(revertLabel, true),
-        collapseUnchanged: folded,
+        original,
+        value,
+        extA: [...common, EditorState.readOnly.of(true), EditorView.editable.of(false)],
+        extB: editing,
+        collapse: folded,
+        revertLabel,
       });
-      v = mv.b;
-      destroy = () => mv.destroy();
+      v = sd.b;
+      destroy = sd.destroy;
     } else {
       v = new EditorView({
         parent: host.current!,
@@ -306,15 +598,56 @@ export default function DiffEditor({
     }
     v.focus();
     view.current = v;
-    return destroy;
+    if (navRef) {
+      // The B side's chunks, unified or split: the cursor goes to the start
+      // of the next / previous one and it scrolls into view.
+      navRef.current = (dir) => {
+        const ed = view.current;
+        const chunks = ed ? (chunksOf(ed.state)?.chunks ?? []) : [];
+        if (!ed || !chunks.length) return;
+        const at = ed.state.selection.main.head;
+        const next =
+          dir === 1
+            ? chunks.find((c) => c.fromB > at)
+            : [...chunks].reverse().find((c) => c.fromB < ed.state.doc.lineAt(at).from);
+        if (!next) return;
+        ed.dispatch({
+          selection: EditorSelection.cursor(next.fromB),
+          effects: EditorView.scrollIntoView(next.fromB, { y: "center" }),
+        });
+        ed.focus();
+      };
+    }
+    return () => {
+      if (navRef) navRef.current = null;
+      destroy();
+    };
     // One mount per view: the parent keys this component by file and shape.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // Annotate on / off without remounting the view.
+  useEffect(() => {
+    view.current?.dispatch({
+      effects: blameSlot.reconfigure(
+        blame
+          ? blameGutter(blame, cb.current.t("changes.notCommitted"), (sha) =>
+              cb.current.onBlameClick?.(sha)
+            )
+          : []
+      ),
+    });
+  }, [blame, blameSlot]);
+
+  const bars = !!onBlock;
+  useEffect(() => {
+    view.current?.dispatch({ effects: barsOn.of(bars) });
+  }, [bars]);
+
   // A value set from outside (Cancel's revert, a save's fresh text).
   useEffect(() => {
     const v = view.current;
-    if (v && v.state.doc.toString() !== value) {
+    if (v && v.state.sliceDoc() !== value) {
       v.dispatch({ changes: { from: 0, to: v.state.doc.length, insert: value } });
     }
   }, [value]);
@@ -324,7 +657,9 @@ export default function DiffEditor({
       ref={host}
       data-testid="lane-file-editor"
       data-layout={layout}
-      className="min-h-0 flex-1 overflow-hidden rounded border border-border-light [&_.cm-mergeView]:h-full [&_.cm-mergeView]:overflow-auto"
+      data-bars={bars}
+      // With the git bars up, a block's local Revert would be a second Undo.
+      className="[&[data-bars=true]_.cm-chunkButtons]:hidden [&[data-bars=true]_.cm-merge-revert_button]:hidden min-h-0 flex-1 overflow-hidden rounded border border-border-light"
     />
   );
 }

client/src/components/lanes/FolderBrowseModal.tsx

@@ -66,6 +66,7 @@ export function FolderBrowseModal({
         role="dialog"
         aria-modal="true"
         aria-label={t("browse.title")}
+        data-tour="folder-browse"
       >
         <div className="border-b border-border p-3">
           <div className="truncate font-mono text-xs text-fg-secondary" title={listing?.path}>

client/src/components/lanes/InterruptedSessionsPrompt.tsx

@@ -0,0 +1,155 @@
+/**
+ * @file InterruptedSessionsPrompt.tsx
+ * @description The app-wide "resume interrupted sessions?" dialog. A session
+ * whose pane died under it — the machine shut down, tmux was killed, the CLI
+ * crashed — is listed by `GET /api/run/interrupted`; the user ticks the ones
+ * to resume (each in the first free tab of its workspace, with its run's
+ * model and effort) or resumes none. Either answer dismisses the whole list,
+ * so it is asked once; a resume that failed stays listed. Refetched on the
+ * `runs_interrupted` broadcast, so a tmux that dies under an open dashboard
+ * asks too. Resuming is the explicit click here, never the dialog opening.
+ *
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { useNavigate } from "react-router-dom";
+import { api, type InterruptedRun } from "../../lib/api";
+import { eventBus } from "../../lib/eventBus";
+import { timeAgo } from "../../lib/format";
+import { toast } from "../../lib/toast";
+import { Checkbox } from "../Checkbox";
+import { ConfirmModal } from "../ConfirmModal";
+import { startInFreeTabDetailed } from "./startSession";
+
+const label = (it: InterruptedRun) => it.lane_title || it.lane_cwd;
+
+export function InterruptedSessionsPrompt() {
+  const { t } = useTranslation("run");
+  const navigate = useNavigate();
+  const [items, setItems] = useState<InterruptedRun[]>([]);
+  const [picked, setPicked] = useState<Set<string>>(new Set());
+  const [busy, setBusy] = useState(false);
+  // A refetch keeps the user's ticks; a session not seen before starts ticked.
+  const seen = useRef(new Set<string>());
+
+  const load = useCallback(() => {
+    api.run
+      .interrupted()
+      .then((r) => {
+        const fresh = r.items.filter((i) => !seen.current.has(i.session_id));
+        fresh.forEach((i) => seen.current.add(i.session_id));
+        setItems(r.items);
+        setPicked((p) => {
+          const next = new Set(r.items.filter((i) => p.has(i.session_id)).map((i) => i.session_id));
+          fresh.forEach((i) => next.add(i.session_id));
+          return next;
+        });
+      })
+      .catch(() => undefined); // a convenience: no prompt when it cannot be read
+  }, []);
+
+  useEffect(load, [load]);
+  useEffect(
+    () =>
+      eventBus.subscribe((msg) => {
+        if (msg.type === "runs_interrupted") load();
+      }),
+    [load]
+  );
+
+  const dismiss = async (sessionIds: string[]) => {
+    if (sessionIds.length) await api.run.dismissInterrupted(sessionIds).catch(toast.error);
+  };
+
+  const resumeNone = async () => {
+    if (busy) return;
+    setBusy(true);
+    await dismiss(items.map((i) => i.session_id));
+    setItems([]);
+    setBusy(false);
+  };
+
+  const resumePicked = async () => {
+    if (busy) return;
+    setBusy(true);
+    const failed = new Set<string>();
+    let first: { runId: string; laneId: number } | null = null;
+    for (const it of items.filter((i) => picked.has(i.session_id))) {
+      try {
+        const r = await startInFreeTabDetailed(it.lane_id, {
+          resumeSessionId: it.session_id,
+          ...(it.model ? { model: it.model } : {}),
+          ...(it.effort ? { effort: it.effort } : {}),
+          // Bypass is a per-run choice, never carried over.
+          ...(it.permission_mode && it.permission_mode !== "bypassPermissions"
+            ? { permissionMode: it.permission_mode }
+            : {}),
+        });
+        first ??= r;
+      } catch (err) {
+        failed.add(it.session_id);
+        toast.error(
+          t("interrupted.failed", {
+            name: label(it),
+            message: err instanceof Error ? err.message : String(err),
+          })
+        );
+      }
+    }
+    await dismiss(items.map((i) => i.session_id).filter((id) => !failed.has(id)));
+    setItems((cur) => cur.filter((i) => failed.has(i.session_id)));
+    setBusy(false);
+    if (first) navigate(`/workspace?lane=${first.laneId}&run=${encodeURIComponent(first.runId)}`);
+  };
+
+  const toggle = (id: string, on: boolean) =>
+    setPicked((p) => {
+      const next = new Set(p);
+      if (on) next.add(id);
+      else next.delete(id);
+      return next;
+    });
+
+  const count = items.filter((i) => picked.has(i.session_id)).length;
+  return (
+    <ConfirmModal
+      open={items.length > 0}
+      title={t("interrupted.title")}
+      message={t("interrupted.message")}
+      confirmLabel={t("interrupted.resume", { count })}
+      cancelLabel={t("interrupted.none")}
+      destructive={false}
+      busy={busy}
+      disabled={count === 0}
+      onConfirm={() => void resumePicked()}
+      onCancel={() => void resumeNone()}
+    >
+      <ul className="mt-3 max-h-80 space-y-1 overflow-y-auto">
+        {items.map((it) => (
+          <li key={it.session_id} className="rounded-md border border-border px-2 py-1.5">
+            <Checkbox
+              checked={picked.has(it.session_id)}
+              onChange={(on) => toggle(it.session_id, on)}
+              disabled={busy}
+              className="w-full"
+              labelClassName="min-w-0 flex-1"
+              label={
+                <span className="block min-w-0 text-left">
+                  <span className="block truncate text-xs text-fg-primary">
+                    {label(it)} · {it.tool}
+                  </span>
+                  <span className="block truncate text-[11px] text-fg-muted">
+                    {it.session_name || it.prompt_preview || it.session_id}
+                    {it.ended_at ? ` · ${timeAgo(it.ended_at)}` : ""}
+                  </span>
+                </span>
+              }
+            />
+          </li>
+        ))}
+      </ul>
+    </ConfirmModal>
+  );
+}

client/src/components/lanes/LaneCard.tsx

@@ -57,7 +57,10 @@ export function useLaneRuntime(laneId: number, bump: number): LaneRuntime | null
         });
     };
     read();
-    const timer = setInterval(read, RUNTIME_REFRESH_MS);
+    const timer = setInterval(
+      () => document.visibilityState === "visible" && read(),
+      RUNTIME_REFRESH_MS
+    );
     return () => {
       alive = false;
       clearInterval(timer);
@@ -88,7 +91,10 @@ function useLaneLocks(laneSlot: number | null): NamedLock[] {
         });
     };
     read();
-    const timer = setInterval(read, LOCKS_REFRESH_MS);
+    const timer = setInterval(
+      () => document.visibilityState === "visible" && read(),
+      LOCKS_REFRESH_MS
+    );
     return () => {
       alive = false;
       clearInterval(timer);
@@ -98,13 +104,6 @@ function useLaneLocks(laneSlot: number | null): NamedLock[] {
   return locks;
 }
 
-export const LIVENESS_DOT: Record<Lane["liveness"], string> = {
-  active: "bg-status-success",
-  // A ring: a surface-4 fill vanished on the light themes.
-  idle: "border border-fg-muted",
-  dead: "bg-status-danger",
-};
-
 export function since(sec: number | null): string {
   if (sec === null) return "—";
   if (sec < 60) return `${sec}s`;

client/src/components/lanes/LaneConflictView.tsx

@@ -38,6 +38,7 @@ function Lines({ lines, className = "" }: { lines: string[]; className?: string
 export function LaneConflictView({
   laneId,
   session,
+  source,
   path,
   onResolved,
   onEdit,
@@ -45,6 +46,8 @@ export function LaneConflictView({
   laneId: number;
   /** Work in that session's own worktree (see `gitTarget`). */
   session?: string;
+  /** Work in that extra folder's repo instead (`lane_sources` id, see `gitTarget`). */
+  source?: number;
   path: string;
   /** The file left the conflict (resolved, or a whole side taken). */
   onResolved: () => void;
@@ -65,7 +68,7 @@ export function LaneConflictView({
     setChoices([]);
     setError(null);
     api.lanes
-      .gitFile(gitTarget(laneId, session), path, "work")
+      .gitFile(gitTarget(laneId, session, source), path, "work")
       .then((r) => {
         if (!live) return;
         setFile(
@@ -78,7 +81,7 @@ export function LaneConflictView({
     return () => {
       live = false;
     };
-  }, [laneId, session, path]);
+  }, [laneId, session, source, path]);
 
   const parts: ConflictPart[] | null = file?.usable ? parseConflicts(file.lines) : null;
   const total = parts ? parts.filter((p) => p.kind === "conflict").length : 0;
@@ -102,15 +105,18 @@ export function LaneConflictView({
     run(async () => {
       if (!parts || !file?.sha) return;
       await api.lanes.gitSaveFile(
-        gitTarget(laneId, session),
+        gitTarget(laneId, session, source),
         path,
         applyChoices(parts, choices).join("\n"),
         file.sha
       );
-      await api.lanes.gitAction(gitTarget(laneId, session), "resolve", { path, side: "done" });
+      await api.lanes.gitAction(gitTarget(laneId, session, source), "resolve", {
+        path,
+        side: "done",
+      });
     });
   const takeAll = (side: "ours" | "theirs") =>
-    run(() => api.lanes.gitAction(gitTarget(laneId, session), "resolve", { path, side }));
+    run(() => api.lanes.gitAction(gitTarget(laneId, session, source), "resolve", { path, side }));
 
   const choose = (i: number, c: ConflictChoice | undefined) =>
     setChoices((prev) => {

client/src/components/lanes/LaneDiffView.tsx

@@ -10,9 +10,15 @@
  *   - The intra-line diff is a common prefix/suffix trim, not a real LCS. It is
  *     right for the case that matters (one edited span on a line), degrades to
  *     "the whole line changed" otherwise, and costs nothing.
- *   - Line pairing for split view happens here, on the rows the server already
- *     numbered. The server stays the single source of what changed; this file
- *     only decides how it looks.
+ *   - Side by side is JetBrains-shaped and laid out here, on the rows the
+ *     server already numbered: within a hunk each column lists only its own
+ *     lines, one after another, so the sides drift apart past a change and a
+ *     curved band in the middle gutter joins each block to its counterpart
+ *     (`lib/diffConnectors.ts`). Only a hunk's END is padded, so the `@@`
+ *     headers — and the two scrollers, kept in step 1:1 — stay level. Every
+ *     split row is ROW_PX tall, which makes a band's y pure arithmetic. The
+ *     server stays the single source of what changed; this file only decides
+ *     how it looks.
  * Past `WINDOW_THRESHOLD` rows a view renders only the rows on screen (plus an
  * overscan) between two spacers. Rows never wrap — the box scrolls sideways —
  * so every windowed row is pinned to `ROW_PX` and the range is pure arithmetic
@@ -38,6 +44,7 @@ import { useTranslation } from "react-i18next";
 import { ChevronDown, ChevronUp } from "lucide-react";
 import { canonicalLang, highlight, tokenClass } from "../../lib/highlight";
 import type { LaneChangeFile, LaneDiffHunk, LaneDiffLine } from "../../lib/types";
+import { bandPath } from "../../lib/diffConnectors";
 
 export type DiffLayout = "unified" | "split";
 
@@ -220,29 +227,28 @@ function emphasis(
   };
 }
 
-type PairRow = { left: LaneDiffLine | null; right: LaneDiffLine | null; emph: EmphPair | null };
-type EmphPair = { del: [number, number]; add: [number, number] };
+/** A split-view row: the index in `hunk.lines` each column shows, -1 for the
+ *  padding that closes the shorter side of a hunk. */
+type SplitRow = { left: number; right: number };
 /** A hunk's split-view rows plus each paired line's emphasis, keyed by its
  *  index in `hunk.lines` (what the unified view renders by). */
-type Analysed = { rows: PairRow[]; emph: Map<number, [number, number]> };
+type Analysed = { rows: SplitRow[]; emph: Map<number, [number, number]> };
 
 // Keyed by the hunk object: a hunk is immutable once fetched, so both split
 // columns and every re-render of the same data share one pass. A refetch
 // brings new objects and the old entries go with them.
 const analysed = new WeakMap<LaneDiffHunk, Analysed>();
 
-/** Pair each run of removed lines with the run of added lines following it,
- *  carrying indices so emphasis lands without searching the hunk again. */
+/** Pair each run of removed lines with the run of added lines following it
+ *  for emphasis, keyed by line index so it lands without searching the hunk
+ *  again; and pack each column's own lines into the split rows. */
 export function analyseHunk(hunk: LaneDiffHunk): Analysed {
   const hit = analysed.get(hunk);
   if (hit) return hit;
   const lines = hunk.lines;
-  const rows: PairRow[] = [];
   const emph = new Map<number, [number, number]>();
-  for (let i = 0; i < lines.length; ) {
-    const line = lines[i]!;
-    if (line.type === "ctx") {
-      rows.push({ left: line, right: line, emph: null });
+  for (let i = 0; i < lines.length;) {
+    if (lines[i]!.type === "ctx") {
       i += 1;
       continue;
     }
@@ -260,9 +266,18 @@ export function analyseHunk(hunk: LaneDiffHunk): Analysed {
         emph.set(delStart + k, e.del);
         emph.set(addStart + k, e.add);
       }
-      rows.push({ left, right, emph: e });
     }
   }
+  const left: number[] = [];
+  const right: number[] = [];
+  lines.forEach((l, i) => {
+    if (l.type !== "add") left.push(i);
+    if (l.type !== "del") right.push(i);
+  });
+  const rows = Array.from({ length: Math.max(left.length, right.length) }, (_, i) => ({
+    left: left[i] ?? -1,
+    right: right[i] ?? -1,
+  }));
   const out = { rows, emph };
   analysed.set(hunk, out);
   return out;
@@ -351,9 +366,14 @@ export type LaneDiffChange = {
   /** First/last index in `hunk.lines` (unified). */
   firstLine: number;
   lastLine: number;
-  /** First/last split-view row. */
+  /** First split-view row (either side): the bar's arrows scroll here. */
   firstRow: number;
+  /** The right column's row its review bar hangs under. */
   lastRow: number;
+  /** Split-view rows `[from, to)` on each side; empty (`from === to`) is the
+   *  point between two rows where a pure insertion / removal sits. */
+  left: [number, number];
+  right: [number, number];
 };
 
 const blocksOf = new WeakMap<LaneDiffHunk, LaneDiffChange[]>();
@@ -363,23 +383,46 @@ export function changeBlocks(hunk: LaneDiffHunk): LaneDiffChange[] {
   const hit = blocksOf.get(hunk);
   if (hit) return hit;
   const out: LaneDiffChange[] = [];
-  const owner = new Map<LaneDiffLine, LaneDiffChange>();
   hunk.lines.forEach((line, i) => {
     if (line.type === "ctx") return;
     let c = i > 0 && hunk.lines[i - 1]!.type !== "ctx" ? out[out.length - 1] : undefined;
     if (!c) {
-      c = { hunk, block: out.length, firstLine: i, lastLine: i, firstRow: -1, lastRow: -1 };
+      c = {
+        hunk,
+        block: out.length,
+        firstLine: i,
+        lastLine: i,
+        firstRow: -1,
+        lastRow: -1,
+        left: [0, 0],
+        right: [0, 0],
+      };
       out.push(c);
     }
     c.lastLine = i;
-    owner.set(line, c);
-  });
-  analyseHunk(hunk).rows.forEach((r, i) => {
-    const c = (r.left && owner.get(r.left)) || (r.right && owner.get(r.right));
-    if (!c) return;
-    if (c.firstRow < 0) c.firstRow = i;
-    c.lastRow = i;
   });
+  // A side's rows are its lines in order, so a block's rows there are the
+  // count of that side's lines before it, plus its own.
+  for (const c of out) {
+    let l = 0;
+    let r = 0;
+    hunk.lines.forEach((line, i) => {
+      if (i >= c.firstLine) return;
+      if (line.type !== "add") l += 1;
+      if (line.type !== "del") r += 1;
+    });
+    let dl = 0;
+    let dr = 0;
+    for (let i = c.firstLine; i <= c.lastLine; i += 1) {
+      if (hunk.lines[i]!.type === "del") dl += 1;
+      else dr += 1;
+    }
+    c.left = [l, l + dl];
+    c.right = [r, r + dr];
+    c.firstRow = Math.min(l, r);
+    // A pure removal hangs its bar under the right row its band points at.
+    c.lastRow = dr ? r + dr - 1 : Math.max(0, r - 1);
+  }
   blocksOf.set(hunk, out);
   return out;
 }
@@ -397,7 +440,8 @@ const startAtRow = (hunk: LaneDiffHunk, i: number) =>
  *  block's last line. A context rather than a prop because lines render from
  *  four places; `changes` is what the bar's "n of N" and its arrows walk. */
 const HunkActions = createContext<{
-  actions: (change: LaneDiffChange) => ReactNode;
+  /** null = no bar; the anchors still mark each block for navigation. */
+  actions: ((change: LaneDiffChange) => ReactNode) | null;
   changes: LaneDiffChange[];
   go: (index: number) => void;
 } | null>(null);
@@ -414,7 +458,7 @@ function useAnchor(change?: LaneDiffChange) {
 function HunkBar({ change }: { change: LaneDiffChange }) {
   const { t } = useTranslation(["lanes"]);
   const ctx = useContext(HunkActions);
-  if (!ctx) return null;
+  if (!ctx?.actions) return null;
   const index = ctx.changes.indexOf(change);
   const total = ctx.changes.length;
   const nav =
@@ -547,37 +591,36 @@ function longestInHunks(hunks: LaneDiffHunk[]) {
   );
 }
 
+/** One column's row i of a hunk: that side's i-th line, or the padding
+ *  that closes the hunk's shorter side. Always ROW_PX tall (see the header). */
 function SplitLine({
-  row,
+  hunk,
+  i,
   lang,
   side,
-  style,
   bar,
   start,
 }: {
-  row: PairRow;
+  hunk: LaneDiffHunk;
+  i: number;
   lang: string;
   side: "left" | "right";
-  style?: CSSProperties;
   bar?: LaneDiffChange;
   start?: LaneDiffChange;
 }) {
-  const line = side === "left" ? row.left : row.right;
+  const { rows, emph } = analyseHunk(hunk);
+  const at = rows[i]![side];
+  const line = at < 0 ? null : hunk.lines[at]!;
+  const e = at < 0 ? undefined : emph.get(at);
   const anchor = useAnchor(start);
   return (
-    <Row tint={rowTint(line?.type ?? null, !!row.emph)} style={style} anchor={anchor}>
+    <Row tint={rowTint(line?.type ?? null, !!e)} style={FIXED} anchor={anchor}>
       <Gutter
         n={(side === "left" ? line?.oldLine : line?.newLine) ?? null}
         commentable={side === "right"}
       />
       <span className="whitespace-pre px-1">
-        {line ? (
-          <Code
-            text={line.text}
-            lang={lang}
-            emph={side === "left" ? row.emph?.del : row.emph?.add}
-          />
-        ) : null}
+        {line ? <Code text={line.text} lang={lang} emph={e} /> : null}
       </span>
       {bar && <HunkBar change={bar} />}
     </Row>
@@ -598,11 +641,12 @@ function SplitColumn({
     <>
       {hunks.map((hunk, h) => (
         <div key={`${hunk.header}:${h}`}>
-          <HunkHeader hunk={hunk} />
-          {analyseHunk(hunk).rows.map((row, i) => (
+          <HunkHeader hunk={hunk} fixed />
+          {analyseHunk(hunk).rows.map((_, i) => (
             <SplitLine
               key={i}
-              row={row}
+              hunk={hunk}
+              i={i}
               lang={lang}
               side={side}
               // One bar per change block: on the right (new) column only.
@@ -638,10 +682,10 @@ function SplitSlice({
           ) : (
             <SplitLine
               key={range.start + k}
-              row={analyseHunk(hunk).rows[i]!}
+              hunk={hunk}
+              i={i}
               lang={lang}
               side={side}
-              style={FIXED}
               bar={side === "right" ? barAtRow(hunk, i) : undefined}
               start={startAtRow(hunk, i)}
             />
@@ -657,8 +701,7 @@ export function clampScroll(v: number, scrollSize: number, clientSize: number) {
 }
 
 type Axis =
-  | ["scrollLeft", "scrollWidth", "clientWidth"]
-  | ["scrollTop", "scrollHeight", "clientHeight"];
+  ["scrollLeft", "scrollWidth", "clientWidth"] | ["scrollTop", "scrollHeight", "clientHeight"];
 const AXES: Axis[] = [
   ["scrollLeft", "scrollWidth", "clientWidth"],
   ["scrollTop", "scrollHeight", "clientHeight"],
@@ -677,11 +720,48 @@ function follow(src: HTMLElement, dst: HTMLElement) {
   }
 }
 
-/** Both sides, each its own scroller but kept in step on both axes. */
+/** The middle gutter's width: room for an S-curve to read as one. */
+const GUTTER_PX = 36;
+
+const BAND = {
+  add: "fill-status-success/20 stroke-status-success/60",
+  del: "fill-status-danger/20 stroke-status-danger/60",
+  mod: "fill-diff-mod/20 stroke-diff-mod/60",
+} as const;
+
+/** Every change block's band, in the columns' content coordinates: a hunk's
+ *  header is item `h`, so its row r starts at (h + 1 + r) × ROW_PX. */
+function bandsOf(items: Item[]) {
+  const out: { d: string; kind: keyof typeof BAND; top: number; bottom: number }[] = [];
+  items.forEach(({ hunk, i }, h) => {
+    if (i >= 0) return;
+    for (const c of changeBlocks(hunk)) {
+      const [y0, y1, z0, z1] = [...c.left, ...c.right].map((r) => (h + 1 + r) * ROW_PX) as [
+        number,
+        number,
+        number,
+        number,
+      ];
+      const kind = y0 === y1 ? "add" : z0 === z1 ? "del" : "mod";
+      out.push({
+        d: bandPath(GUTTER_PX, y0, y1, z0, z1),
+        kind,
+        top: Math.min(y0, z0),
+        bottom: Math.max(y1, z1),
+      });
+    }
+  });
+  return out;
+}
+
+/** Both sides, each its own scroller but kept in step on both axes, and the
+ *  gutter between them that draws each block's band, scrolled with them. */
 function SplitView({ hunks, lang, fill }: { hunks: LaneDiffHunk[]; lang: string; fill: boolean }) {
   const left = useRef<HTMLDivElement>(null);
   const right = useRef<HTMLDivElement>(null);
+  const mid = useRef<HTMLDivElement>(null);
   const items = useMemo(() => flatten(hunks, "split"), [hunks]);
+  const bands = useMemo(() => bandsOf(items), [items]);
   const minWidth = useMemo(() => `calc(${longestInHunks(hunks)}ch + 3rem)`, [hunks]);
   const win = useWindow(items.length);
 
@@ -695,8 +775,11 @@ function SplitView({ hunks, lang, fill }: { hunks: LaneDiffHunk[]; lang: string;
     const dst = from === "left" ? right.current : left.current;
     if (!src || !dst) return;
     follow(src, dst);
+    if (mid.current) mid.current.scrollTop = src.scrollTop;
     win.onScroll(src);
   };
+  // Windowed, only the bands that reach the rendered rows are drawn.
+  const [from, to] = [win.range.start * ROW_PX, win.range.end * ROW_PX];
 
   const column = (side: "left" | "right") =>
     win.on ? (
@@ -717,11 +800,33 @@ function SplitView({ hunks, lang, fill }: { hunks: LaneDiffHunk[]; lang: string;
       >
         {column("left")}
       </div>
+      <div
+        ref={mid}
+        data-testid="lane-diff-connectors"
+        aria-hidden
+        className="shrink-0 overflow-hidden border-x border-border-light bg-surface-1"
+        style={{ width: GUTTER_PX }}
+      >
+        {/* Taller than the columns by a scrollbar, so it can scroll as far. */}
+        <svg width={GUTTER_PX} height={items.length * ROW_PX + 24} className="block">
+          {bands
+            .filter((b) => b.bottom >= from && b.top <= to)
+            .map((b) => (
+              <path
+                key={`${b.top}:${b.d}`}
+                d={b.d}
+                data-kind={b.kind}
+                className={BAND[b.kind]}
+                vectorEffect="non-scaling-stroke"
+              />
+            ))}
+        </svg>
+      </div>
       <div
         ref={right}
         data-testid="lane-diff-split-right"
         onScroll={() => sync("right")}
-        className="w-1/2 min-w-0 overflow-auto border-l border-border-light"
+        className="w-1/2 min-w-0 overflow-auto"
       >
         {column("right")}
       </div>
@@ -826,7 +931,9 @@ export function LaneDiffView({
     const at = items.findIndex((it) => it.hunk === target.hunk && it.i === target.firstLine);
     if (at >= 0 && layout === "unified") el.scrollTop = at * ROW_PX;
   };
-  const review = hunkActions && hunks ? { actions: hunkActions, changes, go } : null;
+  // Provided without actions too: every block's first row carries its
+  // `data-change-index`, which the panel's F7 / Shift+F7 walk in any range.
+  const review = hunks ? { actions: hunkActions ?? null, changes, go } : null;
 
   if (file.binary)
     return <p className="px-2 py-1 text-[10px] text-fg-muted">{t("changes.binary")}</p>;

client/src/components/lanes/LaneGitBar.tsx

@@ -19,8 +19,8 @@
  * is `EGITAUTH` (issue #45): the dashboard's git has no terminal to prompt
  * in, so a remote wanting a login opens a form here and the SAME action is
  * resent with the typed credential — the token is never rendered back.
- * Fetch, pull, push and publish say so in a toast when they succeed; a merge
- * asks through the themed confirm; the rows wrap in a narrow panel.
+ * Fetch, pull, push and publish say so in a toast when they succeed; a merge,
+ * a push, a publish and a branch delete ask through the themed confirm first; the rows wrap in a narrow panel.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
@@ -45,14 +45,7 @@ import { isSubmitEnter } from "../../lib/keys";
 import type { LaneGitFacts, LaneWorktree } from "../../lib/types";
 
 type Action =
-  | "fetch"
-  | "pull"
-  | "push"
-  | "switch"
-  | "branch-create"
-  | "branch-delete"
-  | "merge"
-  | "publish";
+  "fetch" | "pull" | "push" | "switch" | "branch-create" | "branch-delete" | "merge" | "publish";
 type RunBody = Parameters<typeof api.lanes.gitAction>[2];
 
 const LOCAL_HOST = /^(localhost|127\.|\[::1\])/;
@@ -95,6 +88,7 @@ function Btn({
 export function LaneGitBar({
   laneId,
   session,
+  source,
   git,
   onChanged,
   onNewLane,
@@ -103,6 +97,8 @@ export function LaneGitBar({
   laneId: number;
   /** Work in that session's own worktree (see `gitTarget`). */
   session?: string;
+  /** Work in that extra folder's repo instead (`lane_sources` id, see `gitTarget`). */
+  source?: number;
   git: LaneGitFacts;
   /** Rendered at the start of the action row: the header's branch line, so
    *  the facts and the buttons that act on them read as one row. */
@@ -165,7 +161,7 @@ export function LaneGitBar({
     setBusy(action);
     setError(null);
     try {
-      const res = await api.lanes.gitAction(gitTarget(lane, session), action, body || {});
+      const res = await api.lanes.gitAction(gitTarget(lane, session, source), action, body || {});
       // Landed after a lane switch: every write below belongs to the lane
       // no longer shown.
       if (laneNow.current !== lane) return;
@@ -218,7 +214,7 @@ export function LaneGitBar({
 
   const refreshBranches = async () => {
     try {
-      const r = await api.lanes.gitBranches(gitTarget(laneId, session));
+      const r = await api.lanes.gitBranches(gitTarget(laneId, session, source));
       if (laneNow.current !== laneId) return;
       setBranches(r.branches);
       setWorktrees(r.worktrees || []);
@@ -234,6 +230,45 @@ export function LaneGitBar({
     await refreshBranches();
   };
 
+  // Writes that leave this machine (push, publish) or delete a ref ask
+  // first. Asked HERE, at the click — never inside `run` — so the retry a git
+  // login sends is not asked twice.
+  const confirmRun = async (
+    opts: { title: string; message: string; destructive?: boolean },
+    action: Action,
+    body?: RunBody
+  ) => {
+    if (await confirmDialog({ destructive: false, confirmLabel: opts.title, ...opts })) {
+      void run(action, body);
+    }
+  };
+  const push = () =>
+    confirmRun(
+      git.upstream
+        ? {
+            title: t("gitBar.push"),
+            message: t("gitBar.pushConfirm", {
+              count: git.ahead ?? 0,
+              branch: git.branch,
+              upstream: git.upstream,
+            }),
+          }
+        : {
+            title: t("gitBar.publishBranch"),
+            message: t("gitBar.publishBranchConfirm", { branch: git.branch }),
+          },
+      "push"
+    );
+  const publish = () =>
+    confirmRun(
+      {
+        title: t("gitBar.publishApply"),
+        message: t("gitBar.publishConfirm", { branch: git.branch, url: url.trim() }),
+      },
+      "publish",
+      { url: url.trim() }
+    );
+
   const merge = async (branch: string) => {
     const ok = await confirmDialog({
       title: t("gitBar.merge"),
@@ -322,7 +357,11 @@ export function LaneGitBar({
               icon={<ArrowDown className="h-3.5 w-3.5" />}
               busy={busy === "pull"}
               disabled={!git.hasRemote || !!busy || merging}
-              title={merging ? t("gitBar.merging") : t("gitBar.pullHint")}
+              title={
+                merging
+                  ? t("gitBar.merging", { op: git.operation ?? "merge" })
+                  : t("gitBar.pullHint")
+              }
               onClick={() => run("pull")}
             />
             <Btn
@@ -338,7 +377,7 @@ export function LaneGitBar({
                   ? t("gitBar.publishBranchHint")
                   : t("gitBar.pushHint")
               }
-              onClick={() => run("push")}
+              onClick={() => void push()}
             />
             {!git.hasRemote && (
               <Btn
@@ -362,7 +401,7 @@ export function LaneGitBar({
               // beats a red box after it.
               title={
                 merging
-                  ? t("gitBar.merging")
+                  ? t("gitBar.merging", { op: git.operation ?? "merge" })
                   : dirty > 0
                     ? t("gitBar.switchDirty")
                     : t("gitBar.switchHint")
@@ -434,7 +473,17 @@ export function LaneGitBar({
             busy={busy === "branch-delete"}
             disabled={!picked || picked === git.branch || !!heldBy.get(picked)}
             title={t("gitBar.branchDeleteHint")}
-            onClick={() => void run("branch-delete", { branch: picked })}
+            onClick={() =>
+              void confirmRun(
+                {
+                  title: t("gitBar.branchDelete"),
+                  message: t("gitBar.branchDeleteConfirm", { branch: picked }),
+                  destructive: true,
+                },
+                "branch-delete",
+                { branch: picked }
+              )
+            }
           />
           {dirty > 0 && (
             <span className="text-[10px] text-status-warning">{t("gitBar.switchDirty")}</span>
@@ -474,7 +523,7 @@ export function LaneGitBar({
             value={url}
             onChange={(e) => setUrl(e.target.value)}
             onKeyDown={(e) => {
-              if (isSubmitEnter(e) && url.trim()) void run("publish", { url: url.trim() });
+              if (isSubmitEnter(e) && url.trim()) void publish();
             }}
             // The server decides which URLs are acceptable (https without a
             // token, ssh, user@host:path); this only names the two usual ones.
@@ -488,7 +537,7 @@ export function LaneGitBar({
             busy={busy === "publish"}
             disabled={!url.trim()}
             title={t("gitBar.publishHint")}
-            onClick={() => void run("publish", { url: url.trim() })}
+            onClick={() => void publish()}
           />
         </div>
       )}

client/src/components/lanes/LaneGitHeader.tsx

@@ -36,7 +36,9 @@ const GIT_REFRESH_MS = 30_000;
 export function useLaneGitFacts(
   laneId: number,
   /** Read that session's own worktree instead (`?session=`). */
-  session?: string
+  session?: string,
+  /** Read that extra folder's repo instead (`?source=`). */
+  source?: number
 ): [LaneGitFacts | null, () => void] {
   const [facts, setFacts] = useState<LaneGitFacts | null>(null);
   // Bumped by the git action bar: a commit or a pull changes every fact on
@@ -54,7 +56,7 @@ export function useLaneGitFacts(
     let alive = true;
     const read = () => {
       api.lanes
-        .git(gitTarget(laneId, session))
+        .git(gitTarget(laneId, session, source))
         .then((f) => {
           if (alive) setFacts(keepIfSame(f));
         })
@@ -65,12 +67,15 @@ export function useLaneGitFacts(
         });
     };
     read();
-    const timer = setInterval(read, GIT_REFRESH_MS);
+    const timer = setInterval(
+      () => document.visibilityState === "visible" && read(),
+      GIT_REFRESH_MS
+    );
     return () => {
       alive = false;
       clearInterval(timer);
     };
-  }, [laneId, session, nonce]);
+  }, [laneId, session, source, nonce]);
 
   return [facts, () => setNonce((n) => n + 1)];
 }
@@ -319,20 +324,23 @@ export function LaneGitCounts({
 export function LaneGitRailCounts({
   laneId,
   session,
+  source,
   onShowAll,
 }: {
   laneId: number;
   session?: string;
+  source?: number;
   /** Opens the Changes panel from the file list's "… more files". */
   onShowAll?: () => void;
 }) {
-  const [git] = useLaneGitFacts(laneId, session);
+  const [git] = useLaneGitFacts(laneId, session, source);
   return git?.available ? <LaneGitCounts git={git} vertical onShowAll={onShowAll} /> : null;
 }
 
 export function LaneGitHeader({
   laneId,
   session,
+  source,
   git,
   onChanged,
   onNewLane,
@@ -340,6 +348,8 @@ export function LaneGitHeader({
   laneId: number;
   /** Work in that session's own worktree (see `gitTarget`). */
   session?: string;
+  /** Work in that extra folder's repo instead (`lane_sources` id, see `gitTarget`). */
+  source?: number;
   git: LaneGitFacts | null;
   /** Called after a git bar action: the facts AND the panel's diff moved. */
   onChanged: () => void;
@@ -371,6 +381,7 @@ export function LaneGitHeader({
       <LaneGitBar
         laneId={laneId}
         session={session}
+        source={source}
         git={git}
         onChanged={onChanged}
         onNewLane={onNewLane}

client/src/components/lanes/SessionReplay.tsx

@@ -108,7 +108,7 @@ export function SessionReplay({
         ? { runId: holder.id, laneId: lane.id, held: true }
         : await startInFreeTabDetailed(lane.id, { resumeSessionId: sessionId, prompt: text });
       setPrompt("");
-      images.forEach((i) => URL.revokeObjectURL(i.url));
+      images.forEach((i) => i.url && URL.revokeObjectURL(i.url));
       setImages([]);
       onResumed(r.runId, r.laneId);
       // Held already: the prompt reached nothing yet — paste it there.
@@ -121,19 +121,23 @@ export function SessionReplay({
   };
 
   return (
-    <div data-testid="session-replay" className="flex min-h-0 flex-1 flex-col gap-2">
+    <div
+      data-testid="session-replay"
+      data-prompt-drop
+      className="flex min-h-0 flex-1 flex-col gap-2"
+    >
       {session && (
         <div className="flex justify-end">
           <SessionResumeButton session={session} />
         </div>
       )}
       <div className="min-h-0 flex-1 overflow-hidden">
-        <ConversationView sessionId={sessionId} />
+        <ConversationView sessionId={sessionId} fill />
       </div>
       {livePane ? (
         <div
           data-testid="session-replay-live"
-          className="flex items-center gap-2 rounded-2xl border border-border p-3 text-xs text-fg-secondary"
+          className="mx-auto flex w-full max-w-3xl items-center gap-2 rounded-2xl border border-border p-3 text-xs text-fg-secondary"
         >
           <span className="min-w-0 flex-1">{t("replay.live")}</span>
           <button
@@ -148,7 +152,7 @@ export function SessionReplay({
       ) : session && !resumable ? (
         <div
           data-testid="session-replay-no-resume"
-          className="flex items-center gap-2 rounded-2xl border border-border p-3 text-xs text-fg-secondary"
+          className="mx-auto flex w-full max-w-3xl items-center gap-2 rounded-2xl border border-border p-3 text-xs text-fg-secondary"
         >
           <span className="min-w-0 flex-1">{t("replay.noResume", { tool })}</span>
           <button
@@ -160,7 +164,7 @@ export function SessionReplay({
           </button>
         </div>
       ) : (
-        <div className="rounded-2xl border border-border p-2 transition-colors focus-within:border-accent/50">
+        <div className="mx-auto w-full max-w-3xl rounded-2xl border border-border p-2 shadow-sm transition-colors focus-within:border-accent/50">
           <PromptEditor
             bare
             images={images}
@@ -173,6 +177,7 @@ export function SessionReplay({
             rows={2}
             slash={tool === "claude"}
             fileCwd={session?.cwd || lane.cwd}
+            lane={lane.id}
           />
           <div className="mt-1 flex items-center gap-2">
             <span className="text-[11px] text-fg-muted">{t("replay.hint")}</span>

client/src/components/lanes/SessionResumeButton.tsx

@@ -25,16 +25,22 @@ import { useLanes } from "../../hooks/useLanes";
 import { ConfirmModal } from "../ConfirmModal";
 import { startInFreeTabDetailed } from "./startSession";
 import { liveRunFor, sessionWorktreeName } from "./WorkspaceSessionList";
+import { usePermissions } from "../AuthGate";
+
+/** A path without its trailing separators — `/` or a Windows `\`. */
+const strip = (p: string) => p.replace(/[\\/]+$/, "");
 
 /** The workspace of this tool whose folder holds `cwd` most deeply — the
  *  same path-boundary rule the server binds hook sessions with. */
 export function owningLane(cwd: string, tool: string, lanes: Lane[]): Lane | null {
   let best: Lane | null = null;
+  const target = strip(cwd);
   for (const l of lanes) {
     if (l.tool !== tool) continue;
-    const root = l.cwd.replace(/\/+$/, "");
-    if (cwd !== root && !cwd.startsWith(root + "/")) continue;
-    if (!best || root.length > best.cwd.replace(/\/+$/, "").length) best = l;
+    const root = strip(l.cwd);
+    if (target !== root && !target.startsWith(root + "/") && !target.startsWith(root + "\\"))
+      continue;
+    if (!best || root.length > strip(best.cwd).length) best = l;
   }
   return best;
 }
@@ -47,6 +53,7 @@ export function SessionResumeButton({
   const { t } = useTranslation("lanes");
   const navigate = useNavigate();
   const { lanes } = useLanes();
+  const { canEditLane } = usePermissions();
   const [runs, setRuns] = useState<RunHandle[] | null>(null);
   const [confirming, setConfirming] = useState<"resume" | "fork" | null>(null);
   const [busy, setBusy] = useState(false);
@@ -72,9 +79,10 @@ export function SessionResumeButton({
       ? null
       : (lanes.find((l) => l.id === session.lane_id && l.tool === tool) ??
         owningLane(session.cwd, tool, lanes));
-  if (!lane || runs === null) return null;
+  // Server mode: an analyst may resume only in a workspace of their own.
+  if (!lane || !canEditLane(lane) || runs === null) return null;
   const run = liveRunFor(lane, runs, session.id);
-  const same = (a: string, b: string) => a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
+  const same = (a: string, b: string) => strip(a) === strip(b);
   // Its own worktree counts too: the server resumes it there (`claude
   // --worktree` sessions), and refuses one whose worktree is gone.
   const resumable =

client/src/components/lanes/WorkspaceContext.tsx

@@ -0,0 +1,559 @@
+/**
+ * @file WorkspaceContext — a workspace's context: Instructions, Memory
+ * (read-only), Context files and Folders (`GET/PUT/POST/DELETE
+ * /api/lanes/:id/sources…`, see server/lib/lane-sources.js). Shown as the
+ * workspace home's right column and, `compact`, folded at the bottom of the
+ * session view's Changes panel. Folder suggestions are the repo's untracked
+ * worktrees from `GET /api/projects`, filtered by Settings → Worktrees.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { FileText, Folder, Pencil, Plus, X } from "lucide-react";
+import { copyText } from "../../lib/clipboard";
+import { dragProjectPath } from "../../lib/promptAttach";
+import { useDialog } from "../../hooks/useDialog";
+import { api, type LaneMemoryFile, type LaneSource, type LaneSourcesView } from "../../lib/api";
+import type { Lane } from "../../lib/types";
+import { useAiTools } from "../../hooks/useAiTools";
+import { useProjectTreePrefs } from "../../lib/projectTreePrefs";
+import { MarkdownPreview } from "../MarkdownPreview";
+import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "../ContextMenu";
+import { PathPickButton } from "../PathPickButton";
+
+function fmtBytes(n: number | null): string {
+  if (!n) return "";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)} KB`;
+  return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+
+const message = (err: unknown) => (err instanceof Error ? err.message : String(err));
+
+/** Keyed by workspace: an open edit or folder form belongs to ONE workspace. */
+export function WorkspaceContext(props: Parameters<typeof ContextBody>[0]) {
+  return <ContextBody key={props.lane.id} {...props} />;
+}
+
+function ContextBody({
+  lane,
+  onSourcesChange,
+  sourcesVersion = 0,
+  compact = false,
+}: {
+  lane: Lane;
+  /** Called with the sources after a folder or file is added or removed. */
+  onSourcesChange?: (view: LaneSourcesView) => void;
+  /** Bumped when the folder list changed elsewhere: the lists re-read. */
+  sourcesVersion?: number;
+  /** The Changes panel's narrow fold: no card, tighter rows. */
+  compact?: boolean;
+}) {
+  const { t } = useTranslation("lanes");
+  const aiTools = useAiTools();
+  const prefs = useProjectTreePrefs();
+  const [error, setError] = useState<string | null>(null);
+  const [view, setView] = useState<LaneSourcesView | null>(null);
+  const [editing, setEditing] = useState<string | null>(null);
+  const [memory, setMemory] = useState<LaneMemoryFile[] | null>(null);
+  const [memoryOpen, setMemoryOpen] = useState(false);
+  const [memoryTab, setMemoryTab] = useState(0);
+  const [folderOpen, setFolderOpen] = useState(false);
+  const [folderPath, setFolderPath] = useState("");
+  const [suggestions, setSuggestions] = useState<string[]>([]);
+  const fileInput = useRef<HTMLInputElement>(null);
+  const [ctxDrag, setCtxDrag] = useState(false);
+  const memoryPanel = useRef<HTMLDivElement>(null);
+  useDialog(memoryOpen && !!memory, memoryPanel, () => setMemoryOpen(false));
+  const sourceCtx = useContextMenu<LaneSource>();
+
+  useEffect(() => {
+    let live = true;
+    api.lanes
+      .sources(lane.id)
+      .then((v) => live && setView(v))
+      .catch((err) => live && setError(message(err)));
+    api.lanes
+      .memory(lane.id)
+      .then((r) => live && setMemory(r.files))
+      .catch(() => live && setMemory([]));
+    return () => {
+      live = false;
+    };
+  }, [lane.id]);
+
+  // Suggestions are read when the folder form opens, not on every visit.
+  useEffect(() => {
+    if (!folderOpen) return;
+    let live = true;
+    api.projects
+      .list()
+      .then(({ projects }) => {
+        if (!live) return;
+        const p = projects.find((x) => x.workspaces.includes(lane.id));
+        const own = new Set((view?.sources ?? []).map((s) => s.path));
+        setSuggestions(
+          !p || !prefs.showUntracked
+            ? []
+            : p.worktrees
+                .filter((w) => w.workspace_id === null && !own.has(w.path))
+                .filter((w) => !(w.source && prefs.hideSources.includes(w.source)))
+                .map((w) => w.path)
+        );
+      })
+      .catch(() => undefined);
+    return () => {
+      live = false;
+    };
+  }, [folderOpen, lane.id, prefs.showUntracked, prefs.hideSources, view?.sources]);
+
+  useEffect(() => {
+    if (!sourcesVersion) return;
+    let live = true;
+    api.lanes
+      .sources(lane.id)
+      .then((v) => live && setView(v))
+      .catch(() => undefined);
+    return () => {
+      live = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- on a bump only
+  }, [sourcesVersion]);
+
+  const run = async (fn: () => Promise<LaneSourcesView>) => {
+    setError(null);
+    try {
+      const next = await fn();
+      setView(next);
+      onSourcesChange?.(next);
+      return true;
+    } catch (err) {
+      setError(message(err));
+      return false;
+    }
+  };
+  const addFiles = async (picked: File[]) => {
+    for (const f of picked) {
+      if (!(await run(() => api.lanes.addFile(lane.id, f)))) break;
+    }
+  };
+
+  const files = (view?.sources ?? []).filter((s) => s.kind === "file");
+  const folders = (view?.sources ?? []).filter((s) => s.kind === "folder");
+  const card = compact
+    ? "border-b border-border/60 px-1 py-2 last:border-b-0"
+    : "border-b border-border px-4 py-4 last:border-b-0";
+  const heading = compact
+    ? "text-xs font-medium text-fg-secondary"
+    : "text-sm font-medium text-fg-primary";
+  const iconBtn =
+    "rounded p-1 text-fg-muted transition-colors hover:bg-surface-4 hover:text-fg-primary disabled:opacity-40";
+
+  return (
+    <>
+      <aside
+        data-testid="workspace-context"
+        aria-label={t("home.contextPanel")}
+        className={compact ? "" : "card w-80 shrink-0 self-start p-0"}
+      >
+        {view && !view.supported && (
+          <p className="border-b border-border px-4 py-3 text-xs text-status-warning">
+            {t("home.unsupported", { tool: aiTools.label(lane.tool) })}
+          </p>
+        )}
+        {error && (
+          <p role="alert" className="border-b border-border px-4 py-2 text-xs text-status-danger">
+            {error}
+          </p>
+        )}
+
+        <section className={card}>
+          <div className="flex items-center justify-between">
+            <h3 className={heading}>{t("home.instructions")}</h3>
+            {editing === null && (
+              <button
+                type="button"
+                aria-label={t("home.edit")}
+                title={t("home.edit")}
+                onClick={() => setEditing(view?.instructions ?? "")}
+                disabled={!view}
+                className={iconBtn}
+              >
+                <Pencil className="h-3.5 w-3.5" />
+              </button>
+            )}
+          </div>
+          {editing === null ? (
+            <p
+              className={`mt-1 ${compact ? "line-clamp-2" : "line-clamp-3"} whitespace-pre-wrap text-xs text-fg-muted`}
+            >
+              {view?.instructions || t("home.instructionsEmpty")}
+            </p>
+          ) : (
+            <div className="mt-2 space-y-2">
+              <textarea
+                data-testid="workspace-instructions"
+                aria-label={t("home.instructions")}
+                autoFocus
+                value={editing}
+                maxLength={view?.maxInstructions}
+                onChange={(e) => setEditing(e.target.value)}
+                rows={compact ? 4 : 6}
+                className="w-full rounded border border-border bg-surface-1 p-2 text-xs text-fg-primary"
+              />
+              <div className="flex justify-end gap-2">
+                <button
+                  type="button"
+                  onClick={() => setEditing(null)}
+                  className="btn-ghost text-xs"
+                >
+                  {t("home.cancel")}
+                </button>
+                <button
+                  type="button"
+                  onClick={async () => {
+                    if (await run(() => api.lanes.setInstructions(lane.id, editing)))
+                      setEditing(null);
+                  }}
+                  className="btn-primary text-xs"
+                >
+                  {t("home.save")}
+                </button>
+              </div>
+            </div>
+          )}
+        </section>
+
+        <section className={card}>
+          <div className="flex items-center justify-between">
+            <h3 className={heading}>{t("home.memory")}</h3>
+            <button
+              type="button"
+              onClick={() => {
+                setMemoryTab(0);
+                setMemoryOpen(true);
+              }}
+              disabled={!memory?.length}
+              className="text-xs text-fg-secondary hover:text-fg-primary disabled:opacity-40"
+            >
+              {t("home.viewMemory")}
+            </button>
+          </div>
+          <p className="mt-1 text-xs text-fg-muted">
+            {memory?.length
+              ? t("home.memoryCount", { count: memory.length })
+              : t("home.memoryEmpty")}
+          </p>
+        </section>
+
+        <section
+          data-testid="workspace-context-files"
+          className={`${card} ${ctxDrag ? "ring-2 ring-accent/50" : ""}`}
+          // Files dragged in from the OS are added like the + button's pick.
+          onDragOver={(e) => {
+            if (!view || !e.dataTransfer.types.includes("Files")) return;
+            e.preventDefault();
+            e.dataTransfer.dropEffect = "copy";
+            setCtxDrag(true);
+          }}
+          onDragLeave={(e) => {
+            if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setCtxDrag(false);
+          }}
+          onDrop={(e) => {
+            setCtxDrag(false);
+            if (!view || e.dataTransfer.files.length === 0) return;
+            e.preventDefault();
+            void addFiles([...e.dataTransfer.files]);
+          }}
+        >
+          <div className="flex items-center justify-between">
+            <h3 className={heading}>{t("home.context")}</h3>
+            <button
+              type="button"
+              aria-label={t("home.addFile")}
+              title={t("home.addFile")}
+              onClick={() => fileInput.current?.click()}
+              disabled={!view}
+              className={iconBtn}
+            >
+              <Plus className="h-3.5 w-3.5" />
+            </button>
+            <input
+              ref={fileInput}
+              data-testid="workspace-file-input"
+              type="file"
+              multiple
+              hidden
+              onChange={(e) => {
+                const picked = [...(e.target.files ?? [])];
+                e.target.value = "";
+                void addFiles(picked);
+              }}
+            />
+          </div>
+          {!compact && <p className="mt-1 text-xs text-fg-muted">{t("home.contextSnapshot")}</p>}
+          {files.length === 0 ? (
+            <button
+              type="button"
+              onClick={() => fileInput.current?.click()}
+              className={`mt-2 w-full rounded-lg border border-dashed border-border px-3 ${compact ? "py-2" : "py-5"} text-center text-xs text-fg-muted hover:border-border-light hover:text-fg-secondary`}
+            >
+              {t("home.contextEmpty")}
+            </button>
+          ) : (
+            <ul className="mt-2 space-y-1">
+              {files.map((f) => (
+                <li
+                  key={f.id}
+                  className="group flex items-center gap-2 text-xs"
+                  onContextMenu={(e) => sourceCtx.open(e, f)}
+                  // Dragged onto a prompt box, it is attached as `@<path>`.
+                  draggable
+                  onDragStart={(e) => dragProjectPath(e, f.path)}
+                >
+                  <FileText className="h-3.5 w-3.5 shrink-0 text-fg-muted" />
+                  <span title={f.path} className="min-w-0 flex-1 truncate text-fg-secondary">
+                    {f.name}
+                  </span>
+                  <span className="shrink-0 text-fg-muted">
+                    {f.missing ? t("home.missing") : fmtBytes(f.size)}
+                  </span>
+                  <button
+                    type="button"
+                    aria-label={`${t("home.remove")} ${f.name}`}
+                    onClick={() => void run(() => api.lanes.removeSource(lane.id, f.id))}
+                    className={`${iconBtn} opacity-0 group-hover:opacity-100 focus:opacity-100`}
+                  >
+                    <X className="h-3 w-3" />
+                  </button>
+                </li>
+              ))}
+            </ul>
+          )}
+        </section>
+
+        <section className={card}>
+          <div className="flex items-center justify-between">
+            <h3 className={heading}>{t("home.folder")}</h3>
+            <button
+              type="button"
+              aria-label={t("home.addFolder")}
+              title={t("home.addFolder")}
+              onClick={() => setFolderOpen((v) => !v)}
+              disabled={!view}
+              className={iconBtn}
+            >
+              <Plus className="h-3.5 w-3.5" />
+            </button>
+          </div>
+          <ul className="mt-2 space-y-1.5">
+            <li
+              className="flex items-start gap-2 text-xs"
+              draggable
+              onDragStart={(e) => dragProjectPath(e, `${lane.cwd}/`)}
+            >
+              <Folder className="mt-0.5 h-3.5 w-3.5 shrink-0 text-fg-muted" />
+              <span className="min-w-0">
+                <span title={lane.cwd} className="block truncate text-fg-secondary">
+                  {lane.cwd.split("/").filter(Boolean).pop() || lane.cwd}
+                </span>
+                <span className="block text-fg-muted">{t("home.ownFolder")}</span>
+              </span>
+            </li>
+            {folders.map((f) => (
+              <li
+                key={f.id}
+                className="group flex items-center gap-2 text-xs"
+                onContextMenu={(e) => sourceCtx.open(e, f)}
+                draggable
+                onDragStart={(e) => dragProjectPath(e, `${f.path}/`)}
+              >
+                <Folder className="h-3.5 w-3.5 shrink-0 text-fg-muted" />
+                <span title={f.path} className="min-w-0 flex-1 truncate text-fg-secondary">
+                  {f.name}
+                  {f.missing && (
+                    <span className="ml-1 text-status-warning">{t("home.missing")}</span>
+                  )}
+                </span>
+                <button
+                  type="button"
+                  aria-label={`${t("home.remove")} ${f.name}`}
+                  onClick={() => void run(() => api.lanes.removeSource(lane.id, f.id))}
+                  className={`${iconBtn} opacity-0 group-hover:opacity-100 focus:opacity-100`}
+                >
+                  <X className="h-3 w-3" />
+                </button>
+              </li>
+            ))}
+          </ul>
+          {folderOpen && (
+            <form
+              className="mt-3 space-y-2"
+              onSubmit={async (e) => {
+                e.preventDefault();
+                if (await run(() => api.lanes.addFolder(lane.id, folderPath.trim()))) {
+                  setFolderPath("");
+                  setFolderOpen(false);
+                }
+              }}
+            >
+              <div className="flex gap-2">
+                <input
+                  data-testid="workspace-folder-input"
+                  aria-label={t("home.folderPath")}
+                  placeholder={t("home.folderPath")}
+                  autoFocus
+                  value={folderPath}
+                  onChange={(e) => setFolderPath(e.target.value)}
+                  className="min-w-0 flex-1 rounded border border-border bg-surface-1 px-2 py-1 font-mono text-[11px] text-fg-primary"
+                />
+                <PathPickButton start={folderPath || lane.cwd} onPick={setFolderPath} />
+                <button type="submit" disabled={!folderPath.trim()} className="btn-ghost text-xs">
+                  {t("home.add")}
+                </button>
+              </div>
+              {suggestions.length > 0 && (
+                <div>
+                  <p className="text-[10px] uppercase tracking-wide text-fg-muted">
+                    {t("home.suggested")}
+                  </p>
+                  <ul className="mt-1 space-y-0.5">
+                    {suggestions.map((p) => (
+                      <li key={p}>
+                        <button
+                          type="button"
+                          onClick={() => setFolderPath(p)}
+                          title={p}
+                          className="w-full truncate rounded px-1 text-left font-mono text-[11px] text-fg-secondary hover:bg-surface-3"
+                        >
+                          {p}
+                        </button>
+                      </li>
+                    ))}
+                  </ul>
+                </div>
+              )}
+            </form>
+          )}
+        </section>
+      </aside>
+
+      {memoryOpen && memory && (
+        <div
+          className="fixed inset-0 z-40 flex items-center justify-center bg-black/60 p-4"
+          role="presentation"
+          onClick={() => setMemoryOpen(false)}
+        >
+          <div
+            ref={memoryPanel}
+            role="dialog"
+            aria-modal="true"
+            aria-label={t("home.memory")}
+            onClick={(e) => e.stopPropagation()}
+            className="flex max-h-[85vh] w-full max-w-3xl flex-col rounded-xl border border-border bg-surface-1 p-5 shadow-xl"
+          >
+            <div className="mb-3 flex shrink-0 items-center justify-between">
+              <h2 className="text-sm font-semibold text-fg-primary">{t("home.memory")}</h2>
+              <button
+                type="button"
+                autoFocus
+                aria-label={t("home.close")}
+                onClick={() => setMemoryOpen(false)}
+                className={iconBtn}
+              >
+                <X className="h-4 w-4" />
+              </button>
+            </div>
+            <div
+              role="tablist"
+              aria-label={t("home.memory")}
+              // Wraps, so every file is reachable without a horizontal wheel (a
+              // hidden-scrollbar row cut the rest off); past ~3 rows it scrolls
+              // with a visible bar. shrink-0: a long file must not squeeze it.
+              className="mb-3 flex max-h-28 shrink-0 flex-wrap gap-1.5 overflow-y-auto border-b border-border/60 pb-2"
+            >
+              {memory.map((f, i) => (
+                <button
+                  key={f.path}
+                  type="button"
+                  role="tab"
+                  id={`workspace-memory-tab-${i}`}
+                  aria-controls="workspace-memory-panel"
+                  tabIndex={i === memoryTab ? 0 : -1}
+                  title={f.path}
+                  aria-selected={i === memoryTab}
+                  onClick={() => setMemoryTab(i)}
+                  // APG tabs: arrows move (and select), one tab stop.
+                  onKeyDown={(e) => {
+                    const n = memory.length;
+                    const to =
+                      e.key === "ArrowRight"
+                        ? (i + 1) % n
+                        : e.key === "ArrowLeft"
+                          ? (i - 1 + n) % n
+                          : e.key === "Home"
+                            ? 0
+                            : e.key === "End"
+                              ? n - 1
+                              : null;
+                    if (to === null) return;
+                    e.preventDefault();
+                    setMemoryTab(to);
+                    document.getElementById(`workspace-memory-tab-${to}`)?.focus();
+                  }}
+                  className={`flex-shrink-0 whitespace-nowrap rounded-lg border px-3 py-1.5 font-mono text-xs transition-colors ${
+                    i === memoryTab
+                      ? "border-accent/30 bg-accent/15 text-accent"
+                      : "border-border text-fg-secondary hover:bg-surface-3 hover:text-fg-primary"
+                  }`}
+                >
+                  {f.label}
+                </button>
+              ))}
+            </div>
+            {memory[memoryTab] && (
+              <div
+                role="tabpanel"
+                id="workspace-memory-panel"
+                aria-labelledby={`workspace-memory-tab-${memoryTab}`}
+                className="min-h-0 flex-1 overflow-y-auto"
+              >
+                <MarkdownPreview text={memory[memoryTab].content} />
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+
+      {sourceCtx.menu && (
+        <ContextMenu
+          x={sourceCtx.menu.x}
+          y={sourceCtx.menu.y}
+          onClose={sourceCtx.close}
+          testId={`workspace-source-menu-${sourceCtx.menu.item.id}`}
+        >
+          <MenuItem
+            onSelect={() => {
+              void copyText(sourceCtx.menu!.item.path);
+              sourceCtx.close();
+            }}
+          >
+            {t("menu.copyPath")}
+          </MenuItem>
+          <MenuSeparator />
+          <MenuItem
+            danger
+            onSelect={() => {
+              const id = sourceCtx.menu!.item.id;
+              sourceCtx.close();
+              void run(() => api.lanes.removeSource(lane.id, id));
+            }}
+          >
+            {t("home.remove")}
+          </MenuItem>
+        </ContextMenu>
+      )}
+    </>
+  );
+}

client/src/components/lanes/WorkspaceHome.tsx

@@ -5,48 +5,41 @@
  * then opens it (`&run=<runId>`) — the one place a session starts WITH a
  * prompt (the session view's tab bar `+` only starts a bare CLI or a shell,
  * `ConsoleTabs.tsx`). Inside
- * the box, like Claude Desktop's: AI (the session's own tool, the workspace's
- * by default) and one Model chip (`ModelMenu`: the tool's own list or the
- * router's models, plus Effort); under it the quieter choices — AI Router
+ * the box, like Claude Desktop's: the `+` menu (`ChatAddMenu`: upload, or
+ * attach a project file, a context file or a recent upload), AI (the session's own tool, the workspace's
+ * by default; its last row, **Open terminal**, is no AI — it starts a plain
+ * shell tab at once, like the tab bar's New terminal) and one Model chip (`ModelMenu`: the tool's own list or the
+ * proxy's models, plus Effort); under it the quieter choices — AI Proxy
  * (Native or a profile), Permission (Claude's mode, Codex's sandbox/approval,
  * a catalog tool's bypass) and Local / New worktree — the workspace's Recents — the sessions it
  * owns and has not archived (`?lane=&archived=0`, with each one's state dot,
  * **Show more** past the first page, and the sidebar row's Rename/Archive in
  * its right-click menu), then the archived ones folded with Unarchive; a live session opens its pane,
  * any other its conversation (`&session=`, `SessionReplay`), nothing is resumed — and on the right its context: Instructions, Memory (read-only), Context files and
- * Folders (`GET/PUT/POST/DELETE /api/lanes/:id/sources…`, see
- * server/lib/lane-sources.js). Folder suggestions are the repo's untracked
- * worktrees from `GET /api/projects`, filtered by Settings → Worktrees.
+ * Folders (`WorkspaceContext.tsx`, also folded at the bottom of the Changes panel).
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
 import { Checkbox } from "../Checkbox";
-import { copyText } from "../../lib/clipboard";
 import { isSubmitEnter } from "../../lib/keys";
 import { confirmDialog } from "../../lib/confirm";
-import { useDialog } from "../../hooks/useDialog";
 import { useEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useNavigate } from "react-router-dom";
 import {
   ArchiveRestore,
   ShieldAlert,
-  FileText,
   Folder,
   GitBranch,
   MoreHorizontal,
-  Pencil,
   ArrowUp,
-  Plus,
-  X,
+  SquareTerminal,
 } from "lucide-react";
 import {
   api,
   type CodexApproval,
   type CodexSandbox,
   type EffortLevel,
-  type LaneMemoryFile,
-  type LaneSource,
   type LaneSourcesView,
   type ModelChoice,
   type PermissionMode,
@@ -55,16 +48,16 @@ import {
 import type { Lane, Project, Session } from "../../lib/types";
 import { fmtCost, timeAgo } from "../../lib/format";
 import { useAiTools } from "../../hooks/useAiTools";
-import { useProjectTreePrefs } from "../../lib/projectTreePrefs";
 import { ModelMenu, PromptEditor, promptWithImages, type PromptImage } from "../run/RunSetup";
+import { ChatAddMenu } from "../run/ChatAddMenu";
+import { addAttachments } from "../../lib/promptAttach";
 import { AiToolIcon } from "../AiToolIcon";
-import { RouterPicker, routerArg, useAiRouters, useSessionRouter } from "../run/RouterPicker";
+import { ProxyPicker, proxyArg, useAiProxies, useSessionProxy } from "../run/ProxyPicker";
 import { Select } from "../Select";
-import { MarkdownPreview } from "../MarkdownPreview";
 import { WorkspaceRowMenu, type WorkspaceMenuAction } from "./WorkspaceRowMenu";
 import { workspaceName } from "./WorkspaceRow";
 import { SessionMenu } from "./SessionMenu";
-import { ContextMenu, MenuItem, MenuSeparator, menuPoint, useContextMenu } from "../ContextMenu";
+import { menuPoint, useContextMenu } from "../ContextMenu";
 import {
   liveRunFor,
   SessionFold,
@@ -82,14 +75,8 @@ export {
   startInFreeTabDetailed,
 } from "./startSession";
 import { startInFreeTab } from "./startSession";
-import { PathPickButton } from "../PathPickButton";
-
-function fmtBytes(n: number | null): string {
-  if (!n) return "";
-  if (n < 1024) return `${n} B`;
-  if (n < 1024 * 1024) return `${Math.round(n / 1024)} KB`;
-  return `${(n / 1024 / 1024).toFixed(1)} MB`;
-}
+import { WorkspaceContext } from "./WorkspaceContext";
+import { readDefaultMode } from "../../lib/sessionDefaults";
 
 /** Recents' page size; Show more adds another. */
 const RECENT_PAGE = 30;
@@ -101,6 +88,9 @@ type HomeProps = Parameters<typeof HomeBody>[0];
 /** Keyed by workspace: every piece of state below (a half-typed prompt, the
  *  model, an open folder form, a late upload's answer) belongs to ONE
  *  workspace, and the page swaps `lane` without unmounting. */
+/** The AI menu row that opens a terminal; no catalog id can collide (ids are slugs). */
+const OPEN_TERMINAL = "__terminal__";
+
 export function WorkspaceHome(props: HomeProps) {
   return <HomeBody key={props.lane.id} {...props} />;
 }
@@ -109,50 +99,74 @@ function HomeBody({
   lane,
   onMenuAction,
   onRenamed,
+  onSourcesChange,
+  sourcesVersion = 0,
 }: {
   lane: Lane;
   /** Row-menu items the page carries out (its modals); rename is done here. */
   onMenuAction: (action: WorkspaceMenuAction) => void;
   /** Called after a rename, so the page re-reads the lane list. */
   onRenamed?: () => void;
+  /** Called with the sources after a folder or file is added or removed. */
+  onSourcesChange?: (view: LaneSourcesView) => void;
+  /** Bumped when the folder list changed elsewhere (the Changes panel's
+   *  Close repository): the Folder list re-reads. */
+  sourcesVersion?: number;
 }) {
   const { t } = useTranslation("lanes");
   const navigate = useNavigate();
   const aiTools = useAiTools();
-  const prefs = useProjectTreePrefs();
   // The NEW session's AI tool — its own choice, the workspace's by default.
   const [tool, setTool] = useState(lane.tool);
   const entry = aiTools.byId(tool);
   const claude = tool === "claude";
   const codex = tool === "codex";
-  const [prompt, setPrompt] = useState("");
+  // The half-typed prompt survives leaving the page or the workspace.
+  const draftKey = `agenthub.workspace.draft.${lane.id}`;
+  const [prompt, setPrompt] = useState(() => {
+    try {
+      return localStorage.getItem(draftKey) ?? "";
+    } catch {
+      return "";
+    }
+  });
+  useEffect(() => {
+    try {
+      if (prompt) localStorage.setItem(draftKey, prompt);
+      else localStorage.removeItem(draftKey);
+    } catch {
+      /* storage unavailable: the draft just does not survive */
+    }
+  }, [draftKey, prompt]);
   const [images, setImages] = useState<PromptImage[]>([]);
-  const [router, setRouter] = useSessionRouter();
-  const routers = useAiRouters();
-  // Claude and Codex, also before the catalog has loaded (as RouterPicker).
-  const routerCapable = entry?.routerCapable ?? (claude || codex);
+  const pickFiles = useRef<(() => void) | null>(null);
+  const [proxy, setProxy] = useSessionProxy();
+  const proxies = useAiProxies();
+  // Claude and Codex, also before the catalog has loaded (as ProxyPicker).
+  const proxyCapable = entry?.proxyCapable ?? (claude || codex);
   // A profile picked for a tool that can use one; its models replace the tool's own.
-  const profile = routerCapable
-    ? (routers?.find((r) => r.name === router && !r.builtin) ?? null)
+  const profile = proxyCapable
+    ? (proxies?.find((r) => r.name === proxy && !r.builtin) ?? null)
     : null;
-  const routerModels: ModelChoice[] | undefined = profile
+  const proxyModels: ModelChoice[] | undefined = profile
     ? [
         ...new Set(
           [profile.model, profile.models.opus, profile.models.sonnet, profile.models.haiku].filter(
-            Boolean
+            (m): m is string => !!m
           )
         ),
       ].map((id) => ({ id, label: id }))
     : undefined;
   // The tool's default model (also when the catalog arrives after mount); on
-  // a router, the router's own default. A new tool or router drops the pick.
+  // a proxy, the proxy's own default. A new tool or proxy drops the pick.
   const defaultModel = profile ? "" : (entry?.defaultModel ?? "");
   const [model, setModel] = useState(defaultModel);
   useEffect(() => setModel(defaultModel), [defaultModel, tool, profile?.name]);
   // Claude and Codex always take a model and an effort; a catalog tool a
   // model only when its file names the flag, an effort never.
   const hasModel = claude || codex || !!entry?.modelFlag;
-  const [mode, setMode] = useState<PermissionMode>("auto");
+  // The account's own default (first-run setup) — never bypass.
+  const [mode, setMode] = useState<PermissionMode>(readDefaultMode);
   const [sandbox, setSandbox] = useState<CodexSandbox>("workspace-write");
   const [approval, setApproval] = useState<CodexApproval>("on-request");
   // Per session, never remembered.
@@ -175,21 +189,9 @@ function HomeBody({
   // A Recents row being renamed (its session id) and the draft.
   const [renamingId, setRenamingId] = useState<string | null>(null);
   const [nameDraft, setNameDraft] = useState("");
-  const [view, setView] = useState<LaneSourcesView | null>(null);
-  const [editing, setEditing] = useState<string | null>(null);
-  const [memory, setMemory] = useState<LaneMemoryFile[] | null>(null);
-  const [memoryOpen, setMemoryOpen] = useState(false);
-  const [memoryTab, setMemoryTab] = useState(0);
-  const [folderOpen, setFolderOpen] = useState(false);
-  const [folderPath, setFolderPath] = useState("");
-  const [suggestions, setSuggestions] = useState<string[]>([]);
   const [menuAt, setMenuAt] = useState<{ x: number; y: number } | null>(null);
   const [title, setTitle] = useState<string | null>(null);
-  const fileInput = useRef<HTMLInputElement>(null);
-  const memoryPanel = useRef<HTMLDivElement>(null);
-  useDialog(memoryOpen && !!memory, memoryPanel, () => setMemoryOpen(false));
   const recentCtx = useContextMenu<Session>();
-  const sourceCtx = useContextMenu<LaneSource>();
 
   // A new pane, a pane gone, a session id learned — all move these lane fields.
   const runKey = `${lane.status}:${lane.session_id}:${lane.run_id}`;
@@ -218,25 +220,6 @@ function HomeBody({
     `${runKey}:${version}`
   );
 
-  useEffect(() => {
-    let live = true;
-    setView(null);
-    setMemory(null);
-    setEditing(null);
-    setError(null);
-    api.lanes
-      .sources(lane.id)
-      .then((v) => live && setView(v))
-      .catch((err) => live && setError(message(err)));
-    api.lanes
-      .memory(lane.id)
-      .then((r) => live && setMemory(r.files))
-      .catch(() => live && setMemory([]));
-    return () => {
-      live = false;
-    };
-  }, [lane.id]);
-
   // The repository this workspace belongs to (Settings → Projects used to
   // show this): read once per visit, from the server's cached project list.
   const [project, setProject] = useState<Project | null>(null);
@@ -253,39 +236,21 @@ function HomeBody({
     };
   }, [lane.id]);
 
-  // Suggestions are read when the folder form opens, not on every visit.
-  useEffect(() => {
-    if (!folderOpen) return;
-    let live = true;
-    api.projects
-      .list()
-      .then(({ projects }) => {
-        if (!live) return;
-        const p = projects.find((x) => x.workspaces.includes(lane.id));
-        const own = new Set((view?.sources ?? []).map((s) => s.path));
-        setSuggestions(
-          !p || !prefs.showUntracked
-            ? []
-            : p.worktrees
-                .filter((w) => w.workspace_id === null && !own.has(w.path))
-                .filter((w) => !(w.source && prefs.hideSources.includes(w.source)))
-                .map((w) => w.path)
-        );
-      })
-      .catch(() => undefined);
-    return () => {
-      live = false;
-    };
-  }, [folderOpen, lane.id, prefs.showUntracked, prefs.hideSources, view?.sources]);
-
-  const run = async (fn: () => Promise<LaneSourcesView>) => {
+  // The AI menu's Open terminal: a plain shell in the first free slot, opened
+  // at once — the same start the session view's tab bar `+` makes.
+  const openTerminal = async () => {
+    if (startingRef.current) return;
+    startingRef.current = true;
+    setStarting(true);
     setError(null);
     try {
-      setView(await fn());
-      return true;
+      const runId = await startInFreeTab(lane.id, { shell: true });
+      navigate(`/workspace?lane=${lane.id}&run=${encodeURIComponent(runId)}`);
     } catch (err) {
       setError(message(err));
-      return false;
+    } finally {
+      startingRef.current = false;
+      setStarting(false);
     }
   };
 
@@ -303,7 +268,7 @@ function HomeBody({
         // Only a different tool is named: the workspace's own keeps starting
         // even after it was disabled in Settings.
         ...(tool !== lane.tool ? { tool } : {}),
-        ...routerArg(routerCapable, router),
+        ...proxyArg(proxyCapable, proxy),
         ...(hasModel && model ? { model } : {}),
         ...(claude ? { permissionMode: mode } : {}),
         ...(codex ? { sandbox, approval } : {}),
@@ -312,7 +277,7 @@ function HomeBody({
         ...(claude && inWorktree && project?.root ? { worktree: true } : {}),
       });
       setPrompt("");
-      images.forEach((i) => URL.revokeObjectURL(i.url));
+      images.forEach((i) => i.url && URL.revokeObjectURL(i.url));
       setImages([]);
       navigate(`/workspace?lane=${lane.id}&run=${encodeURIComponent(runId)}`);
     } catch (err) {
@@ -393,10 +358,7 @@ function HomeBody({
           ? t("run:hint.sandboxWarning")
           : null;
 
-  const files = (view?.sources ?? []).filter((s) => s.kind === "file");
-  const folders = (view?.sources ?? []).filter((s) => s.kind === "folder");
   const name = workspaceName(lane);
-  const card = "border-b border-border px-4 py-4 last:border-b-0";
   const iconBtn =
     "rounded p-1 text-fg-muted transition-colors hover:bg-surface-4 hover:text-fg-primary disabled:opacity-40";
 
@@ -405,7 +367,7 @@ function HomeBody({
       data-testid="workspace-home"
       className="mx-auto flex w-full max-w-6xl flex-wrap gap-8 py-2"
     >
-      <div className="min-w-0 flex-1 basis-[28rem]">
+      <div data-prompt-drop className="min-w-0 flex-1 basis-[28rem]">
         <p className="text-xs text-fg-muted">
           {t("home.breadcrumb")} / <span className="text-fg-secondary">{name}</span>
         </p>
@@ -484,31 +446,51 @@ function HomeBody({
             rows={3}
             slash={claude}
             fileCwd={lane.cwd}
+            lane={lane.id}
             images={images}
             onImagesChange={setImages}
             onBusyChange={setUploading}
+            pickFiles={pickFiles}
             bare
           />
           <div className="mt-1 flex items-center gap-1">
+            <ChatAddMenu
+              cwd={lane.cwd}
+              laneId={lane.id}
+              skills={claude}
+              onUpload={() => pickFiles.current?.()}
+              onInsert={(cmd) => setPrompt((p) => `${cmd} ${p.replace(/^\s+/, "")}`)}
+              onAttach={(items) => setImages((prev) => addAttachments(prev, items))}
+            />
             <div data-testid="workspace-home-tool">
               <Select<string>
                 variant="ghost"
                 label={t("home.ai")}
                 value={tool}
                 onChange={(v) => {
+                  // Not a tool: an action. The AI chosen for the prompt stays.
+                  if (v === OPEN_TERMINAL) return void openTerminal();
                   setTool(v);
                   setBypass(false);
                 }}
-                options={toolOptions.map((id) => ({
-                  value: id,
-                  label: aiTools.label(id),
-                  icon: (
-                    <AiToolIcon
-                      tool={{ id, label: aiTools.label(id) }}
-                      className="h-4 w-4 !p-0.5"
-                    />
-                  ),
-                }))}
+                options={[
+                  ...toolOptions.map((id) => ({
+                    value: id,
+                    label: aiTools.label(id),
+                    icon: (
+                      <AiToolIcon
+                        tool={{ id, label: aiTools.label(id) }}
+                        className="h-4 w-4 !p-0.5"
+                      />
+                    ),
+                  })),
+                  {
+                    value: OPEN_TERMINAL,
+                    label: t("home.openTerminal"),
+                    icon: <SquareTerminal className="h-4 w-4 text-fg-muted" />,
+                    divider: true,
+                  },
+                ]}
               />
             </div>
             <div className="ml-auto flex items-center gap-1">
@@ -517,7 +499,7 @@ function HomeBody({
                   value={model}
                   onChange={setModel}
                   tool={tool}
-                  choices={routerModels}
+                  choices={proxyModels}
                   {...(hasEffort ? { effort, onEffortChange: setEffort } : {})}
                 />
               )}
@@ -540,12 +522,12 @@ function HomeBody({
           data-testid="workspace-home-options"
           className="mt-1.5 flex flex-wrap items-center gap-0.5 px-1"
         >
-          <RouterPicker
+          <ProxyPicker
             variant="ghost"
             tool={tool}
-            routers={routers}
-            value={router}
-            onChange={setRouter}
+            proxies={proxies}
+            value={proxy}
+            onChange={setProxy}
           />
           {claude && (
             <Select<PermissionMode>
@@ -721,6 +703,16 @@ function HomeBody({
             {t("tree.showMore", { count: Math.min(sessionTotal - sessions.length, RECENT_PAGE) })}
           </button>
         )}
+        {recentLimit > RECENT_PAGE && sessionTotal > RECENT_PAGE && (
+          <button
+            type="button"
+            data-testid="workspace-recents-less"
+            onClick={() => setRecentLimit(RECENT_PAGE)}
+            className="ml-3 mt-1 text-xs text-fg-muted hover:text-fg-primary"
+          >
+            {t("tree.showLess")}
+          </button>
+        )}
         <div className="mt-2">
           <SessionFold
             testId={`workspace-archived-${lane.id}`}
@@ -735,345 +727,11 @@ function HomeBody({
         </div>
       </div>
 
-      <aside
-        data-testid="workspace-context"
-        aria-label={t("home.contextPanel")}
-        className="card w-80 shrink-0 self-start p-0"
-      >
-        {view && !view.supported && (
-          <p className="border-b border-border px-4 py-3 text-xs text-status-warning">
-            {t("home.unsupported", { tool: aiTools.label(lane.tool) })}
-          </p>
-        )}
-
-        <section className={card}>
-          <div className="flex items-center justify-between">
-            <h3 className="text-sm font-medium text-fg-primary">{t("home.instructions")}</h3>
-            {editing === null && (
-              <button
-                type="button"
-                aria-label={t("home.edit")}
-                title={t("home.edit")}
-                onClick={() => setEditing(view?.instructions ?? "")}
-                disabled={!view}
-                className={iconBtn}
-              >
-                <Pencil className="h-3.5 w-3.5" />
-              </button>
-            )}
-          </div>
-          {editing === null ? (
-            <p className="mt-1 line-clamp-3 whitespace-pre-wrap text-xs text-fg-muted">
-              {view?.instructions || t("home.instructionsEmpty")}
-            </p>
-          ) : (
-            <div className="mt-2 space-y-2">
-              <textarea
-                data-testid="workspace-instructions"
-                aria-label={t("home.instructions")}
-                autoFocus
-                value={editing}
-                maxLength={view?.maxInstructions}
-                onChange={(e) => setEditing(e.target.value)}
-                rows={6}
-                className="w-full rounded border border-border bg-surface-1 p-2 text-xs text-fg-primary"
-              />
-              <div className="flex justify-end gap-2">
-                <button
-                  type="button"
-                  onClick={() => setEditing(null)}
-                  className="btn-ghost text-xs"
-                >
-                  {t("home.cancel")}
-                </button>
-                <button
-                  type="button"
-                  onClick={async () => {
-                    if (await run(() => api.lanes.setInstructions(lane.id, editing)))
-                      setEditing(null);
-                  }}
-                  className="btn-primary text-xs"
-                >
-                  {t("home.save")}
-                </button>
-              </div>
-            </div>
-          )}
-        </section>
-
-        <section className={card}>
-          <div className="flex items-center justify-between">
-            <h3 className="text-sm font-medium text-fg-primary">{t("home.memory")}</h3>
-            <button
-              type="button"
-              onClick={() => {
-                setMemoryTab(0);
-                setMemoryOpen(true);
-              }}
-              disabled={!memory?.length}
-              className="text-xs text-fg-secondary hover:text-fg-primary disabled:opacity-40"
-            >
-              {t("home.viewMemory")}
-            </button>
-          </div>
-          <p className="mt-1 text-xs text-fg-muted">
-            {memory?.length
-              ? t("home.memoryCount", { count: memory.length })
-              : t("home.memoryEmpty")}
-          </p>
-        </section>
-
-        <section className={card}>
-          <div className="flex items-center justify-between">
-            <h3 className="text-sm font-medium text-fg-primary">{t("home.context")}</h3>
-            <button
-              type="button"
-              aria-label={t("home.addFile")}
-              title={t("home.addFile")}
-              onClick={() => fileInput.current?.click()}
-              disabled={!view}
-              className={iconBtn}
-            >
-              <Plus className="h-3.5 w-3.5" />
-            </button>
-            <input
-              ref={fileInput}
-              data-testid="workspace-file-input"
-              type="file"
-              multiple
-              hidden
-              onChange={async (e) => {
-                const picked = [...(e.target.files ?? [])];
-                e.target.value = "";
-                for (const f of picked) {
-                  if (!(await run(() => api.lanes.addFile(lane.id, f)))) break;
-                }
-              }}
-            />
-          </div>
-          {files.length === 0 ? (
-            <button
-              type="button"
-              onClick={() => fileInput.current?.click()}
-              className="mt-2 w-full rounded-lg border border-dashed border-border px-3 py-5 text-center text-xs text-fg-muted hover:border-border-light hover:text-fg-secondary"
-            >
-              {t("home.contextEmpty")}
-            </button>
-          ) : (
-            <ul className="mt-2 space-y-1">
-              {files.map((f) => (
-                <li
-                  key={f.id}
-                  className="group flex items-center gap-2 text-xs"
-                  onContextMenu={(e) => sourceCtx.open(e, f)}
-                >
-                  <FileText className="h-3.5 w-3.5 shrink-0 text-fg-muted" />
-                  <span title={f.path} className="min-w-0 flex-1 truncate text-fg-secondary">
-                    {f.name}
-                  </span>
-                  <span className="shrink-0 text-fg-muted">
-                    {f.missing ? t("home.missing") : fmtBytes(f.size)}
-                  </span>
-                  <button
-                    type="button"
-                    aria-label={`${t("home.remove")} ${f.name}`}
-                    onClick={() => void run(() => api.lanes.removeSource(lane.id, f.id))}
-                    className={`${iconBtn} opacity-0 group-hover:opacity-100 focus:opacity-100`}
-                  >
-                    <X className="h-3 w-3" />
-                  </button>
-                </li>
-              ))}
-            </ul>
-          )}
-        </section>
-
-        <section className={card}>
-          <div className="flex items-center justify-between">
-            <h3 className="text-sm font-medium text-fg-primary">{t("home.folder")}</h3>
-            <button
-              type="button"
-              aria-label={t("home.addFolder")}
-              title={t("home.addFolder")}
-              onClick={() => setFolderOpen((v) => !v)}
-              disabled={!view}
-              className={iconBtn}
-            >
-              <Plus className="h-3.5 w-3.5" />
-            </button>
-          </div>
-          <ul className="mt-2 space-y-1.5">
-            <li className="flex items-start gap-2 text-xs">
-              <Folder className="mt-0.5 h-3.5 w-3.5 shrink-0 text-fg-muted" />
-              <span className="min-w-0">
-                <span title={lane.cwd} className="block truncate text-fg-secondary">
-                  {lane.cwd.split("/").filter(Boolean).pop() || lane.cwd}
-                </span>
-                <span className="block text-fg-muted">{t("home.ownFolder")}</span>
-              </span>
-            </li>
-            {folders.map((f) => (
-              <li
-                key={f.id}
-                className="group flex items-center gap-2 text-xs"
-                onContextMenu={(e) => sourceCtx.open(e, f)}
-              >
-                <Folder className="h-3.5 w-3.5 shrink-0 text-fg-muted" />
-                <span title={f.path} className="min-w-0 flex-1 truncate text-fg-secondary">
-                  {f.name}
-                  {f.missing && (
-                    <span className="ml-1 text-status-warning">{t("home.missing")}</span>
-                  )}
-                </span>
-                <button
-                  type="button"
-                  aria-label={`${t("home.remove")} ${f.name}`}
-                  onClick={() => void run(() => api.lanes.removeSource(lane.id, f.id))}
-                  className={`${iconBtn} opacity-0 group-hover:opacity-100 focus:opacity-100`}
-                >
-                  <X className="h-3 w-3" />
-                </button>
-              </li>
-            ))}
-          </ul>
-          {folderOpen && (
-            <form
-              className="mt-3 space-y-2"
-              onSubmit={async (e) => {
-                e.preventDefault();
-                if (await run(() => api.lanes.addFolder(lane.id, folderPath.trim()))) {
-                  setFolderPath("");
-                  setFolderOpen(false);
-                }
-              }}
-            >
-              <div className="flex gap-2">
-                <input
-                  data-testid="workspace-folder-input"
-                  aria-label={t("home.folderPath")}
-                  placeholder={t("home.folderPath")}
-                  autoFocus
-                  value={folderPath}
-                  onChange={(e) => setFolderPath(e.target.value)}
-                  className="min-w-0 flex-1 rounded border border-border bg-surface-1 px-2 py-1 font-mono text-[11px] text-fg-primary"
-                />
-                <PathPickButton start={folderPath || lane.cwd} onPick={setFolderPath} />
-                <button type="submit" disabled={!folderPath.trim()} className="btn-ghost text-xs">
-                  {t("home.add")}
-                </button>
-              </div>
-              {suggestions.length > 0 && (
-                <div>
-                  <p className="text-[10px] uppercase tracking-wide text-fg-muted">
-                    {t("home.suggested")}
-                  </p>
-                  <ul className="mt-1 space-y-0.5">
-                    {suggestions.map((p) => (
-                      <li key={p}>
-                        <button
-                          type="button"
-                          onClick={() => setFolderPath(p)}
-                          title={p}
-                          className="w-full truncate rounded px-1 text-left font-mono text-[11px] text-fg-secondary hover:bg-surface-3"
-                        >
-                          {p}
-                        </button>
-                      </li>
-                    ))}
-                  </ul>
-                </div>
-              )}
-            </form>
-          )}
-        </section>
-      </aside>
-
-      {memoryOpen && memory && (
-        <div
-          className="fixed inset-0 z-40 flex items-center justify-center bg-black/60 p-4"
-          role="presentation"
-          onClick={() => setMemoryOpen(false)}
-        >
-          <div
-            ref={memoryPanel}
-            role="dialog"
-            aria-modal="true"
-            aria-label={t("home.memory")}
-            onClick={(e) => e.stopPropagation()}
-            className="flex max-h-[85vh] w-full max-w-3xl flex-col rounded-xl border border-border bg-surface-1 p-5 shadow-xl"
-          >
-            <div className="mb-3 flex shrink-0 items-center justify-between">
-              <h2 className="text-sm font-semibold text-fg-primary">{t("home.memory")}</h2>
-              <button
-                type="button"
-                autoFocus
-                aria-label={t("home.close")}
-                onClick={() => setMemoryOpen(false)}
-                className={iconBtn}
-              >
-                <X className="h-4 w-4" />
-              </button>
-            </div>
-            <div
-              role="tablist"
-              aria-label={t("home.memory")}
-              // Wraps, so every file is reachable without a horizontal wheel (a
-              // hidden-scrollbar row cut the rest off); past ~3 rows it scrolls
-              // with a visible bar. shrink-0: a long file must not squeeze it.
-              className="mb-3 flex max-h-28 shrink-0 flex-wrap gap-1.5 overflow-y-auto border-b border-border/60 pb-2"
-            >
-              {memory.map((f, i) => (
-                <button
-                  key={f.path}
-                  type="button"
-                  role="tab"
-                  id={`workspace-memory-tab-${i}`}
-                  aria-controls="workspace-memory-panel"
-                  tabIndex={i === memoryTab ? 0 : -1}
-                  title={f.path}
-                  aria-selected={i === memoryTab}
-                  onClick={() => setMemoryTab(i)}
-                  // APG tabs: arrows move (and select), one tab stop.
-                  onKeyDown={(e) => {
-                    const n = memory.length;
-                    const to =
-                      e.key === "ArrowRight"
-                        ? (i + 1) % n
-                        : e.key === "ArrowLeft"
-                          ? (i - 1 + n) % n
-                          : e.key === "Home"
-                            ? 0
-                            : e.key === "End"
-                              ? n - 1
-                              : null;
-                    if (to === null) return;
-                    e.preventDefault();
-                    setMemoryTab(to);
-                    document.getElementById(`workspace-memory-tab-${to}`)?.focus();
-                  }}
-                  className={`flex-shrink-0 whitespace-nowrap rounded-lg border px-3 py-1.5 font-mono text-xs transition-colors ${
-                    i === memoryTab
-                      ? "border-accent/30 bg-accent/15 text-accent"
-                      : "border-border text-fg-secondary hover:bg-surface-3 hover:text-fg-primary"
-                  }`}
-                >
-                  {f.label}
-                </button>
-              ))}
-            </div>
-            {memory[memoryTab] && (
-              <div
-                role="tabpanel"
-                id="workspace-memory-panel"
-                aria-labelledby={`workspace-memory-tab-${memoryTab}`}
-                className="min-h-0 flex-1 overflow-y-auto"
-              >
-                <MarkdownPreview text={memory[memoryTab].content} />
-              </div>
-            )}
-          </div>
-        </div>
-      )}
+      <WorkspaceContext
+        lane={lane}
+        onSourcesChange={onSourcesChange}
+        sourcesVersion={sourcesVersion}
+      />
 
       {recentCtx.menu && (
         <SessionMenu
@@ -1091,34 +749,6 @@ function HomeBody({
           onArchive={() => void archiveSession(recentCtx.menu!.item)}
         />
       )}
-      {sourceCtx.menu && (
-        <ContextMenu
-          x={sourceCtx.menu.x}
-          y={sourceCtx.menu.y}
-          onClose={sourceCtx.close}
-          testId={`workspace-source-menu-${sourceCtx.menu.item.id}`}
-        >
-          <MenuItem
-            onSelect={() => {
-              void copyText(sourceCtx.menu!.item.path);
-              sourceCtx.close();
-            }}
-          >
-            {t("menu.copyPath")}
-          </MenuItem>
-          <MenuSeparator />
-          <MenuItem
-            danger
-            onSelect={() => {
-              const id = sourceCtx.menu!.item.id;
-              sourceCtx.close();
-              void run(() => api.lanes.removeSource(lane.id, id));
-            }}
-          >
-            {t("home.remove")}
-          </MenuItem>
-        </ContextMenu>
-      )}
       {menuAt && (
         <WorkspaceRowMenu
           lane={lane}

client/src/components/lanes/WorkspaceRow.tsx

@@ -8,13 +8,14 @@
  * preference kept in localStorage (`laneOrderStorage.ts`), never written to
  * the lane row. The row only STARTS a drag (`LANE_DRAG_TYPE`); the list
  * (`WorkspaceTree.tsx`) takes the drop anywhere, gaps included. F2 renames too; the
- * dot's meaning is screen-reader text, and an idle dot is a ring.
+ * dot's meaning is screen-reader text, and an idle dot is a ring. A `readOnly`
+ * row (another user's workspace, for an analyst) has no menu, rename or `+`.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
 import { useState, type MouseEvent } from "react";
 import { useTranslation } from "react-i18next";
-import { ChevronDown, ChevronRight, MoreHorizontal, Plus } from "lucide-react";
+import { ChevronDown, ChevronRight, Eye, MoreHorizontal, Plus } from "lucide-react";
 import type { Lane } from "../../lib/types";
 import { isSubmitEnter } from "../../lib/keys";
 
@@ -49,6 +50,7 @@ export function workspaceName(lane: Lane): string {
 export function WorkspaceRow({
   lane,
   index,
+  readOnly,
   selected,
   expanded,
   renaming,
@@ -63,6 +65,9 @@ export function WorkspaceRow({
   lane: Lane;
   /** Position in the list — the unit both reorder paths speak in. */
   index: number;
+  /** Set (to its tooltip) for a workspace this user may only read: no menu,
+   *  no rename, no new session. */
+  readOnly?: string;
   selected: boolean;
   expanded: boolean;
   renaming: boolean;
@@ -82,7 +87,12 @@ export function WorkspaceRow({
   const openMenu = (e: MouseEvent) => {
     e.preventDefault();
     e.stopPropagation();
-    onMenu(e.clientX, e.clientY);
+    if (!readOnly) onMenu(e.clientX, e.clientY);
+  };
+  const startRename = () => {
+    if (readOnly) return;
+    setDraft(lane.title || "");
+    onRenameStart();
   };
   const Chevron = expanded ? ChevronDown : ChevronRight;
   const hoverBtn =
@@ -140,22 +150,18 @@ export function WorkspaceRow({
           aria-current={selected ? "true" : undefined}
           // A double-click's second click renames instead of opening again.
           onClick={(e) => e.detail < 2 && onSelect()}
-          onDoubleClick={() => {
-            setDraft(lane.title || "");
-            onRenameStart();
-          }}
+          onDoubleClick={startRename}
           onKeyDown={(e) => {
             if (e.key === "F2") {
               e.preventDefault();
-              setDraft(lane.title || "");
-              onRenameStart();
+              startRename();
               return;
             }
             if (!e.altKey || (e.key !== "ArrowUp" && e.key !== "ArrowDown")) return;
             e.preventDefault();
             onReorder(index, index + (e.key === "ArrowUp" ? -1 : 1));
           }}
-          title={`${lane.cwd}\n${t("row.hint")}`}
+          title={`${lane.cwd}\n${readOnly ?? t("row.hint")}`}
           className="flex min-w-0 flex-1 items-center gap-2 py-1.5 text-left"
         >
           <span aria-hidden className={`h-2 w-2 shrink-0 rounded-full ${workspaceDot(lane)}`} />
@@ -163,7 +169,8 @@ export function WorkspaceRow({
           <span className="truncate text-[13px] font-medium text-fg-primary">{name}</span>
         </button>
       )}
-      {!renaming && (
+      {readOnly && <Eye aria-label={readOnly} className="mr-1 h-3 w-3 shrink-0 text-fg-muted" />}
+      {!renaming && !readOnly && (
         <>
           <button
             type="button"

client/src/components/lanes/WorkspaceSessionList.tsx

@@ -1,7 +1,8 @@
 /**
  * @file WorkspaceSessionList — the sessions under an expanded workspace in the
  * sidebar: the ones the workspace OWNS and has not archived
- * (`GET /api/sessions?lane=<id>&archived=0`, newest first) — never the other
+ * (`GET /api/sessions?lane=<id>&archived=0`, newest first, the ones with a live
+ * pane above the ended ones) — never the other
  * sessions that ran in its folder. A row's dot
  * shows its state (`sessionDot`: live pane, needs you, error) and its right
  * edge the AI tool the session ran on (`sessions.tool`); double-click
@@ -12,43 +13,40 @@
  * (`?lane=<id>&run=<runId>`, its tab in the session view; a live tab whose
  * session has no row yet — a bare tab before its first prompt — is listed as
  * **New session** from the run itself, and a live Terminal tab (`tool: "shell"`,
- * which never has a session) as **Terminal** — and under the sessions the last
- * `CLOSED_TERMINALS` closed ones (`GET /api/run/history?tool=shell`), whose
- * click opens a NEW shell tab (a shell cannot be resumed) and whose hover X or
- * right-click menu forgets the row (`DELETE /api/run/history/:id`); Ctrl/Cmd+click opens
- * it in a split beside the focused pane) — attaching, never starting or
+ * which never has a session) as **Terminal** while it is open — a closed one
+ * leaves no row; Ctrl/Cmd+click opens
+ * it in a split in the tab on screen) — attaching, never starting or
  * resuming anything;
  * any other session opens in its workspace too (`?lane=<id>&session=<id>`,
  * `SessionReplay`): its conversation with a prompt box, resumed only when a
  * message is SENT, because a resume re-reads the whole transcript into context.
  * The list shows `SESSION_LIMIT` rows and a **See all (N more)** under them that
- * loads every one. A
+ * loads every one, then a **Show less** that goes back to `SESSION_LIMIT`. A
  * live tab whose session was archived is not brought back as a New session,
  * and archiving a live one asks first. F2 renames the focused row too; each
- * dot carries its meaning as screen-reader text.
+ * dot carries its meaning as screen-reader text. `readOnly` (another user's
+ * workspace, for an analyst): no live tabs, no rename/archive/menu, and a row
+ * opens the session's analysis page (`/sessions/<id>`) — never a pane or a resume.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
 import { useEffect, useState, type ReactNode } from "react";
 import { confirmDialog } from "../../lib/confirm";
 import { isSubmitEnter } from "../../lib/keys";
-import { Archive, GitBranch, SquareTerminal, X } from "lucide-react";
+import { Archive, GitBranch, SquareTerminal } from "lucide-react";
 import { useTranslation } from "react-i18next";
 import { Link, useNavigate } from "react-router-dom";
-import { api, type RunHandle, type RunHistoryItem } from "../../lib/api";
-import { toast } from "../../lib/toast";
-import { startInFreeTab } from "./startSession";
+import { api, type RunHandle } from "../../lib/api";
 import { isSessionAwaitingInput, type Lane, type Session } from "../../lib/types";
 import { timeAgo } from "../../lib/format";
 import { ConfirmModal } from "../ConfirmModal";
 import { AiToolIcon } from "../AiToolIcon";
 import { useAiTools } from "../../hooks/useAiTools";
-import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "../ContextMenu";
+import { useThrottledValue } from "../../hooks/useThrottledValue";
+import { useContextMenu } from "../ContextMenu";
 import { SessionMenu } from "./SessionMenu";
 
 export const SESSION_LIMIT = 6;
-/** Closed Terminal tabs listed under a workspace's sessions. */
-export const CLOSED_TERMINALS = 3;
 
 /**
  * The live pane holding a session: the run the hooks bound it to
@@ -66,9 +64,10 @@ export function liveRunFor(lane: Lane, runs: RunHandle[], sessionId: string): Ru
 /** The name of the git worktree a session ran in (`claude --worktree` puts it
  *  at `<repo>/.claude/worktrees/<name>`), or null for one in the folder. */
 export function sessionWorktreeName(lane: Lane, s: Session): string | null {
-  const strip = (p: string) => p.replace(/\/+$/, "");
+  // Either separator: a Windows cwd is `D:\repo\.claude\worktrees\<name>`.
+  const strip = (p: string) => p.replace(/[\\/]+$/, "");
   if (!s.cwd || strip(s.cwd) === strip(lane.cwd)) return null;
-  return /\/\.claude\/worktrees\/([^/]+)\/?$/.exec(s.cwd)?.[1] ?? null;
+  return /[\\/]\.claude[\\/]worktrees[\\/]([^\\/]+)[\\/]?$/.exec(s.cwd)?.[1] ?? null;
 }
 
 /** A session row's dot: waiting for the user, failed, held by a live pane, or
@@ -223,6 +222,7 @@ export function WorkspaceSessionList({
   selectedSessionId = null,
   onMatches,
   hidden = false,
+  readOnly = false,
 }: {
   lane: Lane;
   /** Every live dashboard pane, from `GET /api/run`. */
@@ -238,6 +238,8 @@ export function WorkspaceSessionList({
   onMatches?: (count: number) => void;
   /** Mounted only to load and count, during a search that hides the row. */
   hidden?: boolean;
+  /** A workspace this user may only read. */
+  readOnly?: boolean;
 }) {
   const { t } = useTranslation("lanes");
   const navigate = useNavigate();
@@ -266,56 +268,27 @@ export function WorkspaceSessionList({
   );
   // The lane's own session/status/needs-you move on every hook, which is when
   // a session can appear or change state, and a tab opening or getting its
-  // session is too — re-read then, not on a timer.
-  const refreshKey = `${lane.session_id}:${lane.status}:${lane.needs_action}:${version}:${laneRuns
-    .map((r) => `${r.id}=${r.sessionId ?? ""}`)
-    .join(",")}`;
-  // A Terminal tab closing is when one joins the history.
-  const shellKey = liveShells.map((r) => r.id).join(",");
-  const [closedShells, setClosedShells] = useState<RunHistoryItem[]>([]);
-  useEffect(() => {
-    if (hidden) return;
-    let live = true;
-    api.run
-      // Live ones come back too (isLive): ask for enough to fill the list anyway.
-      .history({ laneId: lane.id, tool: "shell", limit: CLOSED_TERMINALS + 10 })
-      .then(
-        (r) => live && setClosedShells(r.items.filter((x) => !x.isLive).slice(0, CLOSED_TERMINALS))
-      )
-      .catch(() => undefined);
-    return () => {
-      live = false;
-    };
-  }, [lane.id, shellKey, hidden]);
-  const reopenShell = async (split: boolean) => {
-    try {
-      const runId = await startInFreeTab(lane.id, { shell: true });
-      navigate(
-        `/workspace?lane=${lane.id}&run=${encodeURIComponent(runId)}`,
-        split ? { state: { split: true } } : undefined
-      );
-    } catch (err) {
-      toast.error(err);
-    }
-  };
-  const closedCtx = useContextMenu<RunHistoryItem>();
-  const forgetShell = async (r: RunHistoryItem) => {
-    try {
-      await api.run.forgetHistory(r.id);
-      setClosedShells((all) => all.filter((x) => x.id !== r.id));
-    } catch (err) {
-      toast.error(err);
-    }
-  };
+  // session is too — re-read then, not on a timer. Throttled to one re-read per
+  // 3 s: two sessions in one workspace flip these on every hook. A rename or an
+  // archive (`version`) re-reads at once.
+  const hookKey = useThrottledValue(
+    `${lane.session_id}:${lane.status}:${lane.needs_action}:${laneRuns
+      .map((r) => `${r.id}=${r.sessionId ?? ""}`)
+      .join(",")}`,
+    3000
+  );
+  const refreshKey = `${hookKey}:${version}`;
   const own = useSessionPage({ lane: lane.id, archived: false, limit }, refreshKey);
   const sessions = own?.sessions ?? (own === null ? null : []);
   const more = own ? Math.max(0, own.total - own.sessions.length) : 0;
 
   const q = query.trim().toLowerCase();
-  const shown = (sessions ?? []).filter(
-    (s) => !q || (s.name ?? "").toLowerCase().includes(q) || s.id.startsWith(q)
-  );
   const runFor = (s: Session) => liveRunFor(lane, liveRuns, s.id);
+  // Live sessions first, ended ones under them — each group stays newest
+  // first (the sort is stable over the server's order).
+  const shown = (sessions ?? [])
+    .filter((s) => !q || (s.name ?? "").toLowerCase().includes(q) || s.id.startsWith(q))
+    .sort((a, b) => Number(!!runFor(b)) - Number(!!runFor(a)));
   // A live tab whose session has no row yet: shown as a New session at the
   // top, like Claude Desktop, until its first hook brings the real row. Not
   // during a search — it has no name to match.
@@ -347,7 +320,7 @@ export function WorkspaceSessionList({
     };
   }, [orphanIds]);
   const fresh =
-    sessions === null || q
+    sessions === null || q || readOnly
       ? []
       : [
           ...laneRuns.filter(
@@ -432,9 +405,7 @@ export function WorkspaceSessionList({
       {error}
     </p>
   );
-  // Not during a search, like the live ones: they have no name to match.
-  const closed = q ? [] : closedShells;
-  if (sessions !== null && shown.length === 0 && fresh.length === 0 && closed.length === 0) {
+  if (sessions !== null && shown.length === 0 && fresh.length === 0) {
     return (
       <>
         <p className="py-1 pl-[42px] text-[11px] text-fg-muted">{t("tree.noSessions")}</p>
@@ -526,6 +497,7 @@ export function WorkspaceSessionList({
                   // A double-click's second click renames; it must not
                   // navigate (a second history entry) on top of the first.
                   if (e.detail > 1) return;
+                  if (readOnly) return navigate(`/sessions/${encodeURIComponent(s.id)}`);
                   navigate(
                     run
                       ? `/workspace?lane=${lane.id}&run=${encodeURIComponent(run.id)}`
@@ -535,19 +507,19 @@ export function WorkspaceSessionList({
                     run && (e.ctrlKey || e.metaKey) ? { state: { split: true } } : undefined
                   );
                 }}
-                onDoubleClick={() => startRename(s)}
+                onDoubleClick={() => !readOnly && startRename(s)}
                 onKeyDown={(e) => {
-                  if (e.key === "F2") {
+                  if (e.key === "F2" && !readOnly) {
                     e.preventDefault();
                     startRename(s);
                   }
                 }}
-                onContextMenu={(e) => sessionCtx.open(e, s)}
+                onContextMenu={readOnly ? undefined : (e) => sessionCtx.open(e, s)}
                 title={`${s.name || s.id}\n${timeAgo(s.last_activity ?? s.started_at)}${
                   sessionWorktreeName(lane, s)
                     ? `\n${t("tree.worktreeSession", { name: sessionWorktreeName(lane, s) })}`
                     : ""
-                }\n${run ? t("tree.splitHint") : t("tree.transcriptHint")}`}
+                }${readOnly ? "" : `\n${run ? t("tree.splitHint") : t("tree.transcriptHint")}`}`}
                 className={`flex w-full items-center gap-2 rounded-md py-1 pl-2 pr-2 text-left text-[12px] ${
                   selected
                     ? "bg-accent/10 text-fg-primary"
@@ -573,60 +545,26 @@ export function WorkspaceSessionList({
                 </span>
                 <AiToolIcon
                   tool={{ id: s.tool || "claude", label: tools.label(s.tool || "claude") }}
-                  className="h-3.5 w-3.5 shrink-0 !p-0 opacity-60 group-hover:invisible"
+                  className={`h-3.5 w-3.5 shrink-0 !p-0 opacity-60 ${readOnly ? "" : "group-hover:invisible"}`}
                 />
               </button>
-              <button
-                type="button"
-                data-testid={`workspace-session-archive-${s.id}`}
-                onClick={() => void archive(s)}
-                title={t("tree.archiveSession")}
-                aria-label={t("tree.archiveSession")}
-                // Invisible, not `hidden`: a keyboard user must be able to
-                // Tab onto it, and it shows when focused.
-                className="absolute right-1 top-1/2 -translate-y-1/2 rounded p-0.5 text-fg-muted opacity-0 hover:bg-surface-4 hover:text-fg-primary focus:opacity-100 group-hover:opacity-100"
-              >
-                <Archive className="h-3.5 w-3.5" />
-              </button>
+              {!readOnly && (
+                <button
+                  type="button"
+                  data-testid={`workspace-session-archive-${s.id}`}
+                  onClick={() => void archive(s)}
+                  title={t("tree.archiveSession")}
+                  aria-label={t("tree.archiveSession")}
+                  // Invisible, not `hidden`: a keyboard user must be able to
+                  // Tab onto it, and it shows when focused.
+                  className="absolute right-1 top-1/2 -translate-y-1/2 rounded p-0.5 text-fg-muted opacity-0 hover:bg-surface-4 hover:text-fg-primary focus:opacity-100 group-hover:opacity-100"
+                >
+                  <Archive className="h-3.5 w-3.5" />
+                </button>
+              )}
             </li>
           );
         })}
-        {closed.map((r) => (
-          <li key={r.id} className="group relative">
-            <button
-              type="button"
-              data-testid={`workspace-terminal-closed-${r.id}`}
-              onClick={(e) => void reopenShell(e.ctrlKey || e.metaKey)}
-              onContextMenu={(e) => closedCtx.open(e, r)}
-              title={t("tree.closedTerminal")}
-              className="flex w-full items-center gap-2 rounded-md py-1 pl-2 pr-2 text-left text-[12px] text-fg-muted hover:bg-surface-3 hover:text-fg-primary"
-            >
-              <span
-                aria-hidden
-                className="h-1.5 w-1.5 shrink-0 rounded-full border border-fg-muted"
-              />
-              <span className="sr-only">{t("tree.state.idle")}</span>
-              <span className="truncate">{t("tabs.terminal")}</span>
-              <span className="ml-auto shrink-0 text-[11px]">
-                {timeAgo(r.ended_at ?? r.started_at, true)}
-              </span>
-              <SquareTerminal
-                aria-hidden
-                className="h-3.5 w-3.5 shrink-0 opacity-70 group-hover:invisible"
-              />
-            </button>
-            <button
-              type="button"
-              data-testid={`workspace-terminal-forget-${r.id}`}
-              onClick={() => void forgetShell(r)}
-              title={t("tree.forgetTerminal")}
-              aria-label={t("tree.forgetTerminal")}
-              className="absolute right-1 top-1/2 -translate-y-1/2 rounded p-0.5 text-fg-muted opacity-0 hover:bg-surface-4 hover:text-fg-primary focus:opacity-100 group-hover:opacity-100"
-            >
-              <X className="h-3.5 w-3.5" />
-            </button>
-          </li>
-        ))}
       </ul>
       {more > 0 && !q && (
         <button
@@ -638,6 +576,16 @@ export function WorkspaceSessionList({
           {t("tree.seeAll", { count: more })}
         </button>
       )}
+      {more === 0 && !q && own && own.total > SESSION_LIMIT && limit > SESSION_LIMIT && (
+        <button
+          type="button"
+          data-testid={`workspace-sessions-less-${lane.id}`}
+          onClick={() => setLimit(SESSION_LIMIT)}
+          className="w-full py-1 pl-[42px] pr-2 text-left text-[11px] text-fg-muted hover:text-fg-primary"
+        >
+          {t("tree.showLess")}
+        </button>
+      )}
       {failure}
       {confirmArchive}
       {ctx.menu && (
@@ -650,42 +598,6 @@ export function WorkspaceSessionList({
           onClose={ctx.close}
         />
       )}
-      {closedCtx.menu && (
-        <ContextMenu
-          x={closedCtx.menu.x}
-          y={closedCtx.menu.y}
-          onClose={closedCtx.close}
-          testId={`terminal-menu-${closedCtx.menu.item.id}`}
-        >
-          <MenuItem
-            onSelect={() => {
-              closedCtx.close();
-              void reopenShell(false);
-            }}
-          >
-            {t("tree.reopenTerminal")}
-          </MenuItem>
-          <MenuItem
-            onSelect={() => {
-              closedCtx.close();
-              void reopenShell(true);
-            }}
-          >
-            {t("sessionMenu.openSplit")}
-          </MenuItem>
-          <MenuSeparator />
-          <MenuItem
-            danger
-            onSelect={() => {
-              const item = closedCtx.menu!.item;
-              closedCtx.close();
-              void forgetShell(item);
-            }}
-          >
-            {t("tree.forgetTerminal")}
-          </MenuItem>
-        </ContextMenu>
-      )}
       {sessionCtx.menu && (
         <SessionMenu
           x={sessionCtx.menu.x}

client/src/components/lanes/__tests__/AddLaneModal.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, waitFor, within } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { AddLaneModal } from "../AddLaneModal";
 import { api } from "../../../lib/api";
@@ -31,7 +31,7 @@ vi.mock("../../../lib/api", () => ({
       profileInit: vi.fn(),
       mcpSync: vi.fn(),
     },
-    aiRouters: { list: vi.fn() },
+    aiProxies: { list: vi.fn() },
     aiTools: { list: vi.fn(), iconUrl: (id: string) => `/api/ai-tools/${id}/icon` },
     run: { start: vi.fn() },
   },
@@ -50,7 +50,7 @@ const tool = (id: string, label: string, over: Partial<AiTool> = {}): AiTool =>
   prompt: { mode: "argv" },
   resume: false,
   bypass: false,
-  routerCapable: false,
+  proxyCapable: false,
   install: null,
   update: null,
   modelFlag: false,
@@ -62,8 +62,8 @@ const tool = (id: string, label: string, over: Partial<AiTool> = {}): AiTool =>
 const TOOLS: AiToolsView = {
   default: "claude",
   tools: [
-    tool("claude", "Claude Code", { launcher: "claude", routerCapable: true, prompt: null }),
-    tool("codex", "Codex", { launcher: "codex", routerCapable: true, prompt: null }),
+    tool("claude", "Claude Code", { launcher: "claude", proxyCapable: true, prompt: null }),
+    tool("codex", "Codex", { launcher: "codex", proxyCapable: true, prompt: null }),
     tool("gemini", "Gemini"),
     tool("aider", "Aider", { installed: false, path: null }),
     tool("grok", "Grok", { enabled: false }),
@@ -119,6 +119,13 @@ function renderModal(over: Partial<React.ComponentProps<typeof AddLaneModal>> =
   );
 }
 
+/** The modal opens on Repo; worktree tests switch to Worktree first. */
+function renderWorktree(over: Partial<React.ComponentProps<typeof AddLaneModal>> = {}) {
+  const r = renderModal(over);
+  fireEvent.click(screen.getByRole("button", { name: "Worktree" }));
+  return r;
+}
+
 /** ConfirmModal focuses its Cancel button on a 0ms timer after mount, which
  *  races userEvent.type() and can eat the first keystroke. Let that timer fire,
  *  then click the field to reclaim focus before typing. */
@@ -127,7 +134,7 @@ async function focusField(user: ReturnType<typeof userEvent.setup>, el: HTMLElem
   await user.click(el);
 }
 
-/** Fills the default "Worktree" mode's form up through a resolved branch
+/** Fills the "Worktree" mode's form up through a resolved branch
  *  list, title, and new-branch name - everything Add lane needs to enable. */
 async function fillWorktreeForm(
   user: ReturnType<typeof userEvent.setup>,
@@ -158,7 +165,7 @@ beforeEach(() => {
     .mockReset()
     .mockResolvedValue({ scaffolded: false, reason: "no detectable Node.js project" });
   vi.mocked(api.lanes.mcpSync).mockReset().mockResolvedValue({ servers: [], profilesSeeded: [] });
-  vi.mocked(api.aiRouters.list).mockReset();
+  vi.mocked(api.aiProxies.list).mockReset();
 });
 
 describe("AddLaneModal — picking an existing branch (issue #34)", () => {
@@ -173,7 +180,7 @@ describe("AddLaneModal — picking an existing branch (issue #34)", () => {
 
   it("lists the repo's existing worktrees once the path resolves", async () => {
     vi.mocked(api.lanes.branches).mockResolvedValue(withWorktrees);
-    renderModal();
+    renderWorktree();
     const user = userEvent.setup();
 
     const repoField = screen.getByLabelText("Source repository");
@@ -188,7 +195,7 @@ describe("AddLaneModal — picking an existing branch (issue #34)", () => {
   it("checks an existing branch out, sending no base", async () => {
     vi.mocked(api.lanes.branches).mockResolvedValue(withWorktrees);
     vi.mocked(api.lanes.worktree).mockResolvedValue({ lane: laneFixture({ id: 9 }) });
-    renderModal();
+    renderWorktree();
     const user = userEvent.setup();
 
     const repoField = screen.getByLabelText("Source repository");
@@ -211,7 +218,7 @@ describe("AddLaneModal — picking an existing branch (issue #34)", () => {
 
   it("greys out a branch another worktree already holds", async () => {
     vi.mocked(api.lanes.branches).mockResolvedValue(withWorktrees);
-    renderModal();
+    renderWorktree();
     const user = userEvent.setup();
 
     const repoField = screen.getByLabelText("Source repository");
@@ -229,7 +236,7 @@ describe("AddLaneModal — picking an existing branch (issue #34)", () => {
   it("lets the server name a new branch when the field is left empty", async () => {
     vi.mocked(api.lanes.branches).mockResolvedValue(withWorktrees);
     vi.mocked(api.lanes.worktree).mockResolvedValue({ lane: laneFixture({ id: 9 }) });
-    renderModal();
+    renderWorktree();
     const user = userEvent.setup();
 
     const repoField = screen.getByLabelText("Source repository");
@@ -253,11 +260,11 @@ describe("AddLaneModal — picking an existing branch (issue #34)", () => {
   });
 });
 
-describe("AddLaneModal — worktree mode (default)", () => {
+describe("AddLaneModal — worktree mode", () => {
   // The branch NAME is no longer part of this list: an empty one means "let
   // the server name it" (issue #34).
   it("disables confirm until a repo, a title and a resolved branch list are all present", () => {
-    renderModal();
+    renderWorktree();
     expect(screen.getByRole("button", { name: "Add workspace" })).toBeDisabled();
   });
 
@@ -267,7 +274,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
       current: "main",
       worktrees: [],
     });
-    renderModal();
+    renderWorktree();
     const user = userEvent.setup();
 
     const repoField = screen.getByLabelText("Source repository");
@@ -284,7 +291,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
 
   it("stays disabled and shows a quiet hint when the path is not a resolvable repo", async () => {
     vi.mocked(api.lanes.branches).mockRejectedValue(new Error("EBADSOURCEREPO"));
-    renderModal();
+    renderWorktree();
     const user = userEvent.setup();
 
     const repoField = screen.getByLabelText("Source repository");
@@ -303,7 +310,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
       current: "main",
       worktrees: [],
     });
-    renderModal();
+    renderWorktree();
     const user = userEvent.setup();
 
     const repoField = screen.getByLabelText("Source repository");
@@ -328,7 +335,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
     vi.mocked(api.lanes.worktree).mockResolvedValue({ lane: laneFixture({ id: 9 }) });
     const onAdded = vi.fn();
     const onClose = vi.fn();
-    renderModal({ onClose, onAdded });
+    renderWorktree({ onClose, onAdded });
     const user = userEvent.setup();
 
     await fillWorktreeForm(user, { title: "New feature", branch: "feat/new-feature" });
@@ -360,7 +367,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
     });
     vi.mocked(api.lanes.worktree).mockRejectedValue(new Error("EWORKTREEDIRCOLLISION"));
     const onClose = vi.fn();
-    renderModal({ onClose });
+    renderWorktree({ onClose });
     const user = userEvent.setup();
 
     await fillWorktreeForm(user, { title: "New feature" });
@@ -385,7 +392,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
       lane: { id: 42, title: "demo", cwd: "/lanes/demo", status: "provisioning" } as Lane,
     });
     const onAdded = vi.fn();
-    renderModal({ onAdded });
+    renderWorktree({ onAdded });
     const user = userEvent.setup();
 
     await fillWorktreeForm(user);
@@ -410,7 +417,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
     vi.mocked(api.lanes.mcpSync).mockRejectedValue(new Error("boom"));
     const onAdded = vi.fn();
     const onClose = vi.fn();
-    renderModal({ onAdded, onClose });
+    renderWorktree({ onAdded, onClose });
     const user = userEvent.setup();
 
     await fillWorktreeForm(user, { title: "demo2" });
@@ -431,7 +438,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
     });
     vi.mocked(api.lanes.mcpSync).mockRejectedValue(new Error("no mcp"));
     const onClose = vi.fn();
-    renderModal({ onClose });
+    renderWorktree({ onClose });
     const user = userEvent.setup();
 
     await fillWorktreeForm(user, { title: "demo3" });
@@ -463,7 +470,7 @@ describe("AddLaneModal — worktree mode (default)", () => {
       .mockResolvedValueOnce({ lane: laneFixture({ id: 45, status: "provisioning" }) })
       .mockResolvedValueOnce({ lane: laneFixture({ id: 45, status: "failed" }) });
     const onAdded = vi.fn();
-    renderModal({ onAdded });
+    renderWorktree({ onAdded });
     const user = userEvent.setup();
 
     await fillWorktreeForm(user, { title: "demo4" });
@@ -477,6 +484,12 @@ describe("AddLaneModal — worktree mode (default)", () => {
 });
 
 describe("AddLaneModal — repo mode (adopt)", () => {
+  it("opens in Repo mode by default, with no branch fields", () => {
+    renderModal();
+    expect(screen.getByRole("button", { name: "Repo" })).toHaveAttribute("aria-pressed", "true");
+    expect(screen.queryByTestId("add-lane-branch-section")).toBeNull();
+  });
+
   it("hides the branch fields and enables confirm on a path alone", async () => {
     renderModal();
     const user = userEvent.setup();
@@ -569,6 +582,19 @@ describe("AddLaneModal — folder browse", () => {
     expect(api.lanes.browse).not.toHaveBeenCalled();
   });
 
+  it("opens the picker on every click into the path field", async () => {
+    vi.mocked(api.lanes.pickPath).mockResolvedValue({ path: "/Users/tester/app" });
+    renderModal();
+    const user = userEvent.setup();
+    const field = document.getElementById("add-lane-repo")!;
+
+    await user.click(field);
+    await waitFor(() => expect(field).toHaveValue("/Users/tester/app"));
+    await user.click(field);
+    await waitFor(() => expect(api.lanes.pickPath).toHaveBeenCalledTimes(2));
+    expect(api.lanes.pickPath).toHaveBeenLastCalledWith("dir", "/Users/tester/app");
+  });
+
   it("falls back to the in-app browser when no native picker is available", async () => {
     noNativePicker();
     vi.mocked(api.lanes.browse).mockResolvedValue({
@@ -639,12 +665,12 @@ describe("AddLaneModal — create/update readme", () => {
   });
 });
 
-describe("AddLaneModal — no router here", () => {
-  it("asks for no AI Router: a new session picks its own", async () => {
+describe("AddLaneModal — no proxy here", () => {
+  it("asks for no AI Proxy: a new session picks its own", async () => {
     renderModal({});
     await screen.findByRole("button", { name: /Claude Code.*Default/ });
-    expect(screen.queryByRole("radio", { name: "AI Router" })).toBeNull();
-    expect(api.aiRouters.list).not.toHaveBeenCalled();
+    expect(screen.queryByRole("radio", { name: "AI Proxy" })).toBeNull();
+    expect(api.aiProxies.list).not.toHaveBeenCalled();
   });
 });
 
@@ -727,7 +753,7 @@ describe("AddLaneModal — working straight on main (no worktree)", () => {
 
   it("jumps to Repo mode from the branch choice", async () => {
     const user = userEvent.setup();
-    renderModal();
+    renderWorktree();
     const repoField = screen.getByLabelText("Source repository");
     await focusField(user, repoField);
     await user.type(repoField, "/Users/tester/projects/repo");

client/src/components/lanes/__tests__/DiffEditor.test.tsx

@@ -1,11 +1,13 @@
 /**
  * @file Tests for the Changes panel's CodeMirror editor: which changed lines
  * count as edited in place (blue) rather than added or removed whole, and the
- * editor's own diff classes on a real mount.
+ * editor's own diff classes on a real mount, the per-block Undo / Keep bar,
+ * and the Add to Chat chip on a selection.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 import { describe, it, expect, vi } from "vitest";
-import { render, waitFor } from "@testing-library/react";
+import { fireEvent, render, waitFor } from "@testing-library/react";
+import { EditorView } from "@codemirror/view";
 import DiffEditor, { keepsText } from "../DiffEditor";
 
 // jsdom lays nothing out; CodeMirror's measuring asks a Range for its boxes.
@@ -72,6 +74,81 @@ describe("DiffEditor", () => {
     );
   });
 
+  it("side by side is JetBrains-shaped: no padding, one curved band per block", async () => {
+    const { container } = render(
+      <DiffEditor
+        layout="split"
+        // Three unchanged lines apart, or the diff joins the two into one chunk.
+        value={"a\nB\nc\nd\nf\nnew one\nnew two\ne"}
+        original={"a\nb\nc\nd\nf\ne"}
+        lang="plain"
+        label="Edit"
+        revertLabel="Revert"
+        onChange={vi.fn()}
+        onSave={vi.fn()}
+      />
+    );
+    await waitFor(() => expect(container.querySelectorAll(".cm-editor")).toHaveLength(2));
+    // Each side scrolls its own lines: nothing is padded to line them up.
+    expect(container.querySelector(".cm-mergeSpacer")).toBeNull();
+    expect(container.querySelectorAll(".cm-scroller")).toHaveLength(2);
+    await waitFor(() =>
+      expect(
+        container.querySelectorAll('[data-testid="lane-editor-connectors"] path')
+      ).toHaveLength(2)
+    );
+    const kinds = [
+      ...container.querySelectorAll<SVGPathElement>('[data-testid="lane-editor-connectors"] path'),
+    ].map((p) => p.dataset.kind);
+    expect(kinds).toEqual(["mod", "add"]);
+  });
+
+  it("» puts the original block back on the right, as an edit", async () => {
+    const onChange = vi.fn();
+    const { container } = render(
+      <DiffEditor
+        layout="split"
+        value={"keep\nconst x = 2;\nend"}
+        original={"keep\nconst x = 1;\nend"}
+        lang="ts"
+        label="Edit"
+        revertLabel="Revert"
+        onChange={onChange}
+        onSave={vi.fn()}
+      />
+    );
+    const button = await waitFor(() => {
+      const b = container.querySelector<HTMLButtonElement>(".cm-merge-revert button");
+      expect(b).not.toBeNull();
+      return b!;
+    });
+    fireEvent.mouseDown(button);
+    expect(onChange).toHaveBeenLastCalledWith("keep\nconst x = 1;\nend");
+  });
+
+  it("folds the same unchanged stretch away on both sides", async () => {
+    const same = Array.from({ length: 30 }, (_, i) => `line ${i}`).join("\n");
+    const { container } = render(
+      <DiffEditor
+        layout="split"
+        collapse
+        value={`${same}\nchanged`}
+        original={`${same}\noriginal`}
+        lang="plain"
+        label="Edit"
+        revertLabel="Revert"
+        onChange={vi.fn()}
+        onSave={vi.fn()}
+      />
+    );
+    await waitFor(() => expect(container.querySelectorAll(".cm-collapsedLines")).toHaveLength(2));
+    const [left, right] = [...container.querySelectorAll<HTMLElement>(".cm-collapsedLines")];
+    expect(left!.textContent).toBe(right!.textContent);
+    // One click opens the stretch on both sides.
+    fireEvent.click(right!);
+    await waitFor(() => expect(container.querySelectorAll(".cm-collapsedLines")).toHaveLength(0));
+  });
+
   it("folds unchanged lines away when collapsed, and offers Revert on a block", async () => {
     const same = Array.from({ length: 30 }, (_, i) => `line ${i}`).join("\n");
     const { container } = render(
@@ -90,4 +167,161 @@ describe("DiffEditor", () => {
     const buttons = [...container.querySelectorAll<HTMLButtonElement>(".cm-chunkButtons button")];
     expect(buttons.filter((b) => !b.hidden).map((b) => b.textContent)).toEqual(["Revert"]);
   });
+
+  it("annotates each line in a gutter, and hands a click its commit", async () => {
+    const onBlameClick = vi.fn();
+    const props = {
+      value: "a\nnew",
+      original: "a",
+      lang: "plain",
+      label: "Edit",
+      revertLabel: "Revert",
+      onChange: vi.fn(),
+      onSave: vi.fn(),
+      onBlameClick,
+    };
+    const sha = "f".repeat(40);
+    const blame = {
+      available: true as const,
+      path: "x",
+      commits: {
+        [sha]: { short: "fffffff", author: "Vi", date: "2026-10-01T00:00:00Z", summary: "s" },
+      },
+      lines: [sha, null],
+    };
+    const { container, rerender } = render(<DiffEditor {...props} />);
+    expect(container.querySelector(".cm-ah-blame")).toBeNull();
+    rerender(<DiffEditor {...props} blame={blame} />);
+    await waitFor(() => expect(container.querySelector(".cm-ah-blame")).not.toBeNull());
+    // The first element is CodeMirror's invisible width spacer.
+    const cells = [...container.querySelectorAll(".cm-ah-blame .cm-gutterElement span")].slice(1);
+    expect(cells.map((c) => c.textContent)).toEqual(["2026-10-01 Vi", "Not committed yet"]);
+    fireEvent.mouseDown(cells[0]!.parentElement!);
+    expect(onBlameClick).toHaveBeenCalledWith(sha);
+  });
+
+  it("puts an Undo + commit-checkbox bar under each block, by line, in place of Revert", async () => {
+    const onBlock = vi.fn();
+    const props = {
+      value: "a\nB\nc\nnew\ne",
+      original: "a\nb\nc\nd\ne",
+      lang: "plain",
+      label: "Edit",
+      revertLabel: "Revert",
+      onChange: vi.fn(),
+      onSave: vi.fn(),
+    };
+    const { container, rerender } = render(
+      <DiffEditor {...props} onBlock={onBlock} blockIncluded={(b) => b.oldFrom === 2} />
+    );
+    await waitFor(() =>
+      expect(container.querySelectorAll('[data-testid="lane-editor-block-bar"]')).toHaveLength(2)
+    );
+    expect(container.querySelector('[data-testid="lane-file-editor"]')).toHaveAttribute(
+      "data-bars",
+      "true"
+    );
+    const [first, second] = [
+      ...container.querySelectorAll<HTMLElement>('[data-testid="lane-editor-block-bar"]'),
+    ];
+    const boxes = [first, second].map((b) => b!.querySelector<HTMLInputElement>("input")!);
+    expect(boxes.map((b) => b.checked)).toEqual([true, false]);
+    fireEvent.click(boxes[1]!);
+    expect(onBlock).toHaveBeenLastCalledWith("include", {
+      oldFrom: 4,
+      oldCount: 1,
+      newFrom: 4,
+      newCount: 1,
+    });
+    // Undo asks twice.
+    const firstUndo = first!.querySelector("button")!;
+    fireEvent.click(firstUndo);
+    expect(onBlock).toHaveBeenCalledTimes(1);
+    fireEvent.click(firstUndo);
+    expect(onBlock).toHaveBeenLastCalledWith("undo", {
+      oldFrom: 2,
+      oldCount: 1,
+      newFrom: 2,
+      newCount: 1,
+    });
+    // Unsaved text (no onBlock): no bars, Revert back.
+    rerender(<DiffEditor {...props} />);
+    await waitFor(() =>
+      expect(container.querySelector('[data-testid="lane-editor-block-bar"]')).toBeNull()
+    );
+    expect(container.querySelector('[data-testid="lane-file-editor"]')).toHaveAttribute(
+      "data-bars",
+      "false"
+    );
+  });
+
+  it.each(["unified", "split"] as const)(
+    "keeps a CRLF file's text as is (%s): no edit at mount, so the bars stay",
+    async (layout) => {
+      const onChange = vi.fn();
+      const { container } = render(
+        <DiffEditor
+          layout={layout}
+          value={"a\r\nB\r\nc"}
+          original={"a\r\nb\r\nc"}
+          lang="plain"
+          label="Edit"
+          revertLabel="Revert"
+          onChange={onChange}
+          onSave={vi.fn()}
+          onBlock={vi.fn()}
+        />
+      );
+      await waitFor(() =>
+        expect(container.querySelectorAll('[data-testid="lane-editor-block-bar"]')).toHaveLength(1)
+      );
+      expect(onChange).not.toHaveBeenCalled();
+      const eds = container.querySelectorAll<HTMLElement>(".cm-editor");
+      const view = EditorView.findFromDOM(eds[eds.length - 1]!)!;
+      expect(view.state.sliceDoc()).toBe("a\r\nB\r\nc");
+      // Only B changed: the CRs are not read as an edit on every line.
+      expect(
+        container
+          .querySelectorAll(".cm-editor")
+          [eds.length - 1]!.querySelectorAll(".cm-changedLine")
+      ).toHaveLength(1);
+    }
+  );
+
+  it("offers Add to Chat on a selection, with its 1-based line range", async () => {
+    const onAddToChat = vi.fn();
+    const { container } = render(
+      <DiffEditor
+        value={"a\nb\nc\nd"}
+        original={"a\nb\nc\nd"}
+        lang="plain"
+        label="Edit"
+        revertLabel="Revert"
+        onChange={vi.fn()}
+        onSave={vi.fn()}
+        onAddToChat={onAddToChat}
+      />
+    );
+    const view = EditorView.findFromDOM(container.querySelector<HTMLElement>(".cm-editor")!)!;
+    expect(container.querySelector('[data-testid="lane-editor-add-to-chat"]')).toBeNull();
+    // b..c, ending at the start of d: d is not taken.
+    view.dispatch({ selection: { anchor: 2, head: 6 } });
+    const chip = await waitFor(() => {
+      const b = container.querySelector<HTMLButtonElement>(
+        '[data-testid="lane-editor-add-to-chat"]'
+      );
+      expect(b).not.toBeNull();
+      return b!;
+    });
+    // A tooltip above the last selected line, never inline at a line's end
+    // (a long line pushed it out of view).
+    expect(chip.classList.contains("cm-tooltip")).toBe(true);
+    expect(chip.closest(".cm-line")).toBeNull();
+    fireEvent.click(chip);
+    expect(onAddToChat).toHaveBeenCalledWith(2, 3);
+    view.dispatch({ selection: { anchor: 6 } });
+    await waitFor(() =>
+      expect(container.querySelector('[data-testid="lane-editor-add-to-chat"]')).toBeNull()
+    );
+  });
 });

client/src/components/lanes/__tests__/InterruptedSessionsPrompt.test.tsx

@@ -0,0 +1,109 @@
+/**
+ * @file InterruptedSessionsPrompt.test.tsx
+ * @description The "resume interrupted sessions?" dialog: it opens only when
+ * the server lists some, resumes only the ticked ones (never a bypass mode
+ * carried over), and either answer dismisses the list — but a resume that
+ * failed stays offered.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter } from "react-router-dom";
+import type { InterruptedRun } from "../../../lib/api";
+
+vi.mock("../startSession", () => ({
+  startInFreeTabDetailed: vi.fn(async (laneId: number) => ({
+    runId: `agenthub-lane-${laneId}-1`,
+    laneId,
+    held: false,
+  })),
+}));
+vi.mock("../../../lib/api", () => ({
+  api: {
+    run: {
+      interrupted: vi.fn(),
+      dismissInterrupted: vi.fn(async () => ({ dismissed: 0 })),
+    },
+  },
+}));
+
+import { api } from "../../../lib/api";
+import { startInFreeTabDetailed } from "../startSession";
+import { InterruptedSessionsPrompt } from "../InterruptedSessionsPrompt";
+
+const row = (session_id: string, lane_id: number, extra: Partial<InterruptedRun> = {}) =>
+  ({
+    id: `agenthub-lane-${lane_id}`,
+    session_id,
+    lane_id,
+    tool: "claude",
+    cwd: "/r",
+    model: null,
+    permission_mode: null,
+    effort: null,
+    prompt_preview: `prompt ${session_id}`,
+    started_at: "2026-10-10T00:00:00Z",
+    ended_at: "2026-10-10T01:00:00Z",
+    lane_title: `ws-${lane_id}`,
+    lane_cwd: "/r",
+    session_name: null,
+    ...extra,
+  }) as InterruptedRun;
+
+const list = (items: InterruptedRun[]) =>
+  vi.mocked(api.run.interrupted).mockResolvedValue({ items });
+
+beforeEach(() => vi.clearAllMocks());
+
+const renderIt = () =>
+  render(
+    <MemoryRouter>
+      <InterruptedSessionsPrompt />
+    </MemoryRouter>
+  );
+
+describe("InterruptedSessionsPrompt", () => {
+  it("shows nothing when no session was interrupted", async () => {
+    list([]);
+    renderIt();
+    await waitFor(() => expect(api.run.interrupted).toHaveBeenCalled());
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+
+  it("resumes only the ticked sessions, then dismisses the list", async () => {
+    list([row("s-a", 1, { permission_mode: "bypassPermissions", model: "opus" }), row("s-b", 2)]);
+    const user = userEvent.setup();
+    renderIt();
+    await screen.findByRole("dialog");
+    await user.click(screen.getByRole("checkbox", { name: /ws-2/ }));
+    await user.click(screen.getByRole("button", { name: /resume 1/i }));
+    await waitFor(() => expect(api.run.dismissInterrupted).toHaveBeenCalledWith(["s-a", "s-b"]));
+    expect(startInFreeTabDetailed).toHaveBeenCalledTimes(1);
+    // The model goes back; a bypass mode is never carried over.
+    expect(startInFreeTabDetailed).toHaveBeenCalledWith(1, {
+      resumeSessionId: "s-a",
+      model: "opus",
+    });
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
+  });
+
+  it("resumes nothing on Don't resume, and keeps a session whose resume failed", async () => {
+    list([row("s-a", 1)]);
+    const user = userEvent.setup();
+    const { unmount } = renderIt();
+    await user.click(await screen.findByText("Don't resume"));
+    await waitFor(() => expect(api.run.dismissInterrupted).toHaveBeenCalledWith(["s-a"]));
+    expect(startInFreeTabDetailed).not.toHaveBeenCalled();
+    unmount();
+
+    vi.clearAllMocks();
+    list([row("s-a", 1), row("s-b", 2)]);
+    vi.mocked(startInFreeTabDetailed).mockRejectedValueOnce(new Error("boom"));
+    renderIt();
+    await user.click(await screen.findByRole("button", { name: /resume 2/i }));
+    await waitFor(() => expect(api.run.dismissInterrupted).toHaveBeenCalledWith(["s-b"]));
+    expect(screen.getByRole("checkbox", { name: /ws-1/ })).toBeInTheDocument();
+  });
+});

client/src/components/lanes/__tests__/LaneCard.test.tsx

@@ -28,7 +28,7 @@ vi.mock("../../../lib/api", () => ({
     locks: {
       list: vi.fn(),
     },
-    aiRouters: {
+    aiProxies: {
       list: vi.fn(),
     },
     run: {
@@ -45,10 +45,10 @@ beforeEach(() => {
   // stack, so the runtime strip and its button stay absent unless a test opts in.
   vi.mocked(api.lanes.runtime).mockReset();
   vi.mocked(api.lanes.runtime).mockResolvedValue({ available: false });
-  // Only the built-in profile by default: a user who never opened the AI Router
+  // Only the built-in profile by default: a user who never opened the AI Proxy
   // tab has nothing to switch between, so the row stays out of every other test.
-  vi.mocked(api.aiRouters.list).mockReset();
-  vi.mocked(api.aiRouters.list).mockResolvedValue({ items: [] });
+  vi.mocked(api.aiProxies.list).mockReset();
+  vi.mocked(api.aiProxies.list).mockResolvedValue({ items: [] });
 });
 vi.mocked(api.locks.list).mockReset();
 vi.mocked(api.locks.list).mockResolvedValue({ locks: [] });

client/src/components/lanes/__tests__/LaneChangesPanel.test.tsx

@@ -6,15 +6,19 @@
  * once, the range toggle changes which comparison is requested, History opens
  * one commit, and Files quick-opens a whole file. Also pins the per-file git
  * writes — including discard needing two clicks before the server hears
- * `confirm` — and the degrade for a cwd git cannot read.
+ * `confirm` — the JetBrains commit (ticked files, Changes ticked and
+ * Unversioned Files not by default, Commit and Push, Add to VCS / .gitignore,
+ * a change block's own checkbox making a hunk-level commit), a file's
+ * history, Annotate, next/previous file, and the degrade for a cwd git
+ * cannot read.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, screen, waitFor, act, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { LaneChangesPanel } from "../LaneChangesPanel";
-import { confirmDiscard } from "../../../lib/confirm";
+import { LaneChangesPanel, gitChangeFor } from "../LaneChangesPanel";
+import { confirmDialog, confirmDiscard } from "../../../lib/confirm";
 import { api } from "../../../lib/api";
 import type { LaneChanges } from "../../../lib/types";
 
@@ -70,6 +74,7 @@ vi.mock("../../../lib/api", () => ({
       gitLs: vi.fn(),
       gitTree: vi.fn(),
       gitTreeAll: vi.fn(),
+      gitBlame: vi.fn(),
     },
   },
 }));
@@ -125,6 +130,11 @@ async function toDiff(user: ReturnType<typeof userEvent.setup>) {
   await user.click(await screen.findByRole("button", { name: "Changes", pressed: true }));
 }
 
+/** The overview row's checkbox for one path. */
+function tickOf(path: string) {
+  return screen.getByRole("checkbox", { name: `Include ${path} in the commit` });
+}
+
 /** The overview row's discard button for one path. */
 function discardOf(path: string) {
   return within(screen.getByTitle(path).closest("li")!).getByRole("button", {
@@ -133,7 +143,6 @@ function discardOf(path: string) {
 }
 
 beforeEach(() => {
-  window.localStorage.removeItem("agenthub.changes.neverStage.7");
   vi.mocked(api.lanes.git).mockReset().mockResolvedValue({ available: false });
   vi.mocked(api.lanes.changes).mockReset();
   vi.mocked(api.lanes.changes).mockResolvedValue(changes());
@@ -153,6 +162,14 @@ beforeEach(() => {
       },
     ],
   });
+  vi.mocked(api.lanes.gitBranches)
+    .mockReset()
+    .mockResolvedValue({
+      available: true,
+      branches: ["feat/thing", "other"],
+      current: "feat/thing",
+      worktrees: [],
+    });
   vi.mocked(api.lanes.gitLs)
     .mockReset()
     .mockResolvedValue({
@@ -238,6 +255,36 @@ describe("LaneChangesPanel", () => {
     expect(view).toHaveTextContent("keep");
   });
 
+  it("opens a file asked for from outside (a chat's Edited files card), once per request", async () => {
+    const view = render(
+      <LaneChangesPanel laneId={7} openRequest={{ path: "server/lib/git-ops.js", nonce: 1 }} />
+    );
+    await waitFor(() =>
+      expect(api.lanes.changes).toHaveBeenCalledWith(7, {
+        range: "work",
+        path: "server/lib/git-ops.js",
+        context: 3,
+      })
+    );
+    vi.mocked(api.lanes.changes).mockClear();
+    // The same request again changes nothing; a new nonce opens the next one.
+    view.rerender(
+      <LaneChangesPanel laneId={7} openRequest={{ path: "server/lib/git-ops.js", nonce: 1 }} />
+    );
+    view.rerender(<LaneChangesPanel laneId={7} openRequest={{ path: "src/main.ts", nonce: 2 }} />);
+    await waitFor(() =>
+      expect(api.lanes.changes).toHaveBeenCalledWith(7, {
+        range: "work",
+        path: "src/main.ts",
+        context: 3,
+      })
+    );
+    expect(api.lanes.changes).not.toHaveBeenCalledWith(
+      7,
+      expect.objectContaining({ path: "server/lib/git-ops.js" })
+    );
+  });
+
   it("asks for every file's hunks in review mode", async () => {
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);
@@ -255,7 +302,8 @@ describe("LaneChangesPanel", () => {
     render(<LaneChangesPanel laneId={7} />);
     await screen.findByTestId("lane-changes-overview");
 
-    await user.click(screen.getByRole("button", { name: "vs base" }));
+    // No git facts (an older server): the base has no name to show.
+    await user.click(screen.getByRole("button", { name: "Compared to base branch" }));
     await waitFor(() => expect(api.lanes.changes).toHaveBeenCalledWith(7, { range: "branch" }));
   });
 
@@ -271,60 +319,36 @@ describe("LaneChangesPanel", () => {
     ).toBeInTheDocument();
   });
 
-  it("stages one file and asks the server for that path alone", async () => {
+  it("adds an unversioned file to VCS, for that path alone, and ticks it", async () => {
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);
     await screen.findByTestId("lane-changes-overview");
 
-    // Both rows offer it (one modified, one untracked); the first is the
-    // modified file the assertion below names.
-    const [stage] = screen.getAllByRole("button", { name: "Stage this file" });
-    await user.click(stage!);
-    expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "stage", {
-      paths: ["server/lib/git-ops.js"],
-    });
-  });
-
-  it("keeps a never-stage file out of Stage all, without telling git", async () => {
-    const user = userEvent.setup();
-    render(<LaneChangesPanel laneId={7} />);
-    await screen.findByTestId("lane-changes-overview");
-    const [keep] = screen.getAllByRole("button", { name: /Never stage/ });
-    await user.click(keep!); // the first row: server/lib/git-ops.js
-    expect(api.lanes.gitAction).not.toHaveBeenCalled();
-    expect(JSON.parse(window.localStorage.getItem("agenthub.changes.neverStage.7")!)).toEqual([
-      "server/lib/git-ops.js",
-    ]);
-    await user.click(screen.getByRole("button", { name: "Stage all (1)" }));
+    // Only the untracked row offers it: a tracked file is already in VCS.
+    const [add, ...more] = screen.getAllByRole("button", { name: "Add to VCS" });
+    expect(more).toHaveLength(0);
+    expect(tickOf("notes.txt")).not.toBeChecked();
+    await user.click(add!);
     expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "stage", { paths: ["notes.txt"] });
-    // And back: the row's button now offers the way out.
-    await user.click(screen.getByRole("button", { name: "Include in Stage all again" }));
-    expect(JSON.parse(window.localStorage.getItem("agenthub.changes.neverStage.7")!)).toEqual([]);
+    await waitFor(() => expect(tickOf("notes.txt")).toBeChecked());
   });
 
-  it("draws a never-stage file orange in the Files tree", async () => {
-    window.localStorage.setItem("agenthub.changes.neverStage.7", JSON.stringify(["notes.txt"]));
-    vi.mocked(api.lanes.gitTree).mockResolvedValue({
-      available: true,
-      path: "",
-      entries: [
-        { name: "notes.txt", path: "notes.txt", dir: false, status: "??" },
-        { name: "a.txt", path: "a.txt", dir: false, status: " M" },
-      ],
-      truncated: false,
-    });
+  it("a group's box unticks, then ticks, every file in it, without telling git", async () => {
     const user = userEvent.setup();
-    render(<Tabbed laneId={7} />);
+    render(<LaneChangesPanel laneId={7} />);
     await screen.findByTestId("lane-changes-overview");
-    await user.click(screen.getByRole("button", { name: "Files" }));
-    const row = async (name: string) => (await screen.findByText(name)).closest("button")!;
-    expect(await row("notes.txt")).toHaveAttribute("data-tree-kept", "true");
-    expect(await row("notes.txt")).toHaveClass("text-kept");
-    expect(await row("a.txt")).not.toHaveAttribute("data-tree-kept");
-    expect(await row("a.txt")).toHaveClass("text-status-warning");
+    await user.click(tickOf("docs/API.md"));
+    const group = screen.getByRole("checkbox", { name: "Tick every file in Changes" });
+    expect(group).toBePartiallyChecked();
+    await user.click(group); // some ticked -> untick all
+    expect(tickOf("server/lib/git-ops.js")).not.toBeChecked();
+    await user.click(group); // -> tick all
+    expect(tickOf("docs/API.md")).toBeChecked();
+    expect(tickOf("server/lib/git-ops.js")).toBeChecked();
+    expect(api.lanes.gitAction).not.toHaveBeenCalled();
   });
 
-  it("lists changes as a folder tree: a folder folds, and stages every file in it", async () => {
+  it("lists changes as a folder tree: a folder folds, and its box unticks every file in it", async () => {
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);
     const list = await screen.findByTestId("lane-changes-overview");
@@ -332,16 +356,15 @@ describe("LaneChangesPanel", () => {
     const folder = within(list).getByTitle("server/lib");
     expect(folder).toHaveTextContent("1 file");
     expect(within(list).getByTitle("server/lib/git-ops.js")).toHaveTextContent("git-ops.js");
+    const box = within(folder.parentElement!).getByRole("checkbox", {
+      name: "Tick every file in server/lib",
+    });
+    expect(box).toBeChecked();
+    await user.click(box);
+    expect(tickOf("server/lib/git-ops.js")).not.toBeChecked();
     await user.click(folder);
     expect(within(list).queryByTitle("server/lib/git-ops.js")).toBeNull();
-    await user.click(
-      within(folder.parentElement!).getByRole("button", {
-        name: "Stage every file in this folder",
-      })
-    );
-    expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "stage", {
-      paths: ["server/lib/git-ops.js"],
-    });
+    expect(api.lanes.gitAction).not.toHaveBeenCalled();
   });
 
   it("heads the panel with the lane's git line, and a stage re-reads it", async () => {
@@ -364,7 +387,7 @@ describe("LaneChangesPanel", () => {
     expect(screen.getByTestId("lane-git-bar")).toBeInTheDocument();
     expect(api.lanes.git).toHaveBeenCalledTimes(1);
 
-    const [stage] = screen.getAllByRole("button", { name: "Stage this file" });
+    const [stage] = screen.getAllByRole("button", { name: "Add to VCS" });
     await user.click(stage!);
     // The header's counts moved with the index: waiting out its 30s poll
     // would leave them wrong beside the list that just changed.
@@ -411,43 +434,61 @@ describe("LaneChangesPanel", () => {
     await waitFor(() => expect(api.lanes.gitLog).toHaveBeenCalledTimes(1));
   });
 
-  it("stages every file the index lacks in one call, from above the list", async () => {
+  it("commits exactly the ticked files: Changes ticked, Unversioned Files not, by default", async () => {
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);
     const list = await screen.findByTestId("lane-changes-overview");
     const actions = screen.getByTestId("lane-changes-actions");
-    // Commit box and Stage all come BEFORE the file list.
+    // The commit box comes BEFORE the file list.
     expect(actions.compareDocumentPosition(list) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
     expect(screen.getByTestId("lane-changes-commit")).toBeInTheDocument();
 
-    await user.click(screen.getByRole("button", { name: "Stage all (2)" }));
-    // The already-staged docs/API.md is not sent again.
-    expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "stage", {
+    await user.click(tickOf("notes.txt"));
+    await user.click(tickOf("docs/API.md"));
+    await user.type(screen.getByLabelText("Commit message"), "fix: picked");
+    await user.click(screen.getByRole("button", { name: "Commit (2)" }));
+    expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "commit", {
+      message: "fix: picked",
       paths: ["server/lib/git-ops.js", "notes.txt"],
     });
   });
 
+  it("Commit and Push commits the ticked files, then pushes", async () => {
+    const user = userEvent.setup();
+    render(<LaneChangesPanel laneId={7} />);
+    await screen.findByTestId("lane-changes-commit");
+    await user.type(screen.getByLabelText("Commit message"), "feat: ship");
+    await user.click(screen.getByRole("button", { name: "Commit and Push" }));
+    await waitFor(() => expect(api.lanes.gitAction).toHaveBeenCalledTimes(2));
+    expect(vi.mocked(api.lanes.gitAction).mock.calls).toEqual([
+      [7, "commit", { message: "feat: ship", paths: ["server/lib/git-ops.js", "docs/API.md"] }],
+      [7, "push", {}],
+    ]);
+  });
+
   it("fills the commit box with the AI-suggested message", async () => {
     vi.mocked(api.lanes.suggestCommitMessage).mockResolvedValue({ message: "docs: update API" });
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);
     await screen.findByTestId("lane-changes-overview");
     await user.click(screen.getByTestId("lane-changes-suggest-message"));
-    expect(api.lanes.suggestCommitMessage).toHaveBeenCalledWith(7);
+    expect(api.lanes.suggestCommitMessage).toHaveBeenCalledWith(7, [
+      "server/lib/git-ops.js",
+      "docs/API.md",
+    ]);
     expect(await screen.findByDisplayValue("docs: update API")).toBeInTheDocument();
   });
 
-  it("lists staged files apart from the changes the next commit leaves behind", async () => {
+  it("lists tracked changes apart from Unversioned Files, staged or not", async () => {
     render(<LaneChangesPanel laneId={7} />);
     const list = await screen.findByTestId("lane-changes-overview");
-    const staged = list.querySelector('[data-group="staged"]') as HTMLElement;
-    const unstaged = list.querySelector('[data-group="unstaged"]') as HTMLElement;
-    expect(within(staged).getByTitle("docs/API.md")).toBeInTheDocument();
-    expect(within(staged).queryByText("notes.txt")).toBeNull();
-    expect(within(unstaged).getByTitle("server/lib/git-ops.js")).toBeInTheDocument();
-    expect(within(unstaged).getByText("notes.txt")).toBeInTheDocument();
-    expect(within(unstaged).queryByTitle("docs/API.md")).toBeNull();
-    expect(screen.getByText("Staged Changes")).toBeInTheDocument();
+    const tracked = list.querySelector('[data-group="changes"]') as HTMLElement;
+    const unversioned = list.querySelector('[data-group="unversioned"]') as HTMLElement;
+    expect(within(tracked).getByTitle("docs/API.md")).toBeInTheDocument();
+    expect(within(tracked).getByTitle("server/lib/git-ops.js")).toBeInTheDocument();
+    expect(within(tracked).queryByText("notes.txt")).toBeNull();
+    expect(within(unversioned).getByText("notes.txt")).toBeInTheDocument();
+    expect(screen.getByText("Unversioned Files")).toBeInTheDocument();
   });
 
   it("reads a whole markdown file rendered after Preview, and back as source after Raw", async () => {
@@ -618,21 +659,21 @@ describe("LaneChangesPanel", () => {
     });
   });
 
-  it("right-click on a changed file offers stage, a two-click discard and copy path", async () => {
+  it("right-click on a changed file offers Commit File, a two-click discard, copy path and patch", async () => {
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);
     const list = await screen.findByTestId("lane-changes-overview");
     const row = within(list).getByTitle("server/lib/git-ops.js");
     const right = () => user.pointer({ keys: "[MouseRight]", target: row });
+    const menu = () => within(screen.getByTestId("lane-changes-file-menu"));
 
+    // Commit File: that file alone is ticked, and the message box has focus.
     await right();
-    await user.click(
-      within(screen.getByTestId("lane-changes-file-menu")).getByText("Stage this file")
-    );
-    expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "stage", {
-      paths: ["server/lib/git-ops.js"],
-    });
-    vi.mocked(api.lanes.gitAction).mockClear();
+    await user.click(menu().getByText("Commit File…"));
+    expect(tickOf("server/lib/git-ops.js")).toBeChecked();
+    expect(tickOf("docs/API.md")).not.toBeChecked();
+    expect(screen.getByLabelText("Commit message")).toHaveFocus();
+    expect(screen.getByRole("button", { name: "Commit (1)" })).toBeInTheDocument();
 
     await right();
     await user.click(screen.getByTestId("lane-changes-menu-discard"));
@@ -645,10 +686,123 @@ describe("LaneChangesPanel", () => {
     });
 
     await right();
-    await user.click(
-      within(screen.getByTestId("lane-changes-file-menu")).getByText("Copy relative path")
-    );
+    await user.click(menu().getByText("Copy relative path"));
     expect(await navigator.clipboard.readText()).toBe("server/lib/git-ops.js");
+
+    // Copy as Patch: that file's diff, read for its path, as a unified patch.
+    vi.mocked(api.lanes.changes).mockResolvedValueOnce(
+      changes({
+        files: [{ ...changes().files![0]!, hunks: [HUNK] } as never],
+      })
+    );
+    await right();
+    await user.click(menu().getByText("Copy as Patch to Clipboard"));
+    await waitFor(async () =>
+      expect(await navigator.clipboard.readText()).toBe(
+        [
+          "diff --git a/server/lib/git-ops.js b/server/lib/git-ops.js",
+          "--- a/server/lib/git-ops.js",
+          "+++ b/server/lib/git-ops.js",
+          "@@ -1,2 +1,3 @@",
+          " keep",
+          "-old line",
+          "+new line",
+          "",
+        ].join("\n")
+      )
+    );
+    expect(api.lanes.changes).toHaveBeenCalledWith(7, {
+      range: "work",
+      path: "server/lib/git-ops.js",
+      context: 3,
+    });
+  });
+
+  it("right-click on an unversioned file offers Add to VCS and Add to .gitignore", async () => {
+    const user = userEvent.setup();
+    render(<LaneChangesPanel laneId={7} />);
+    const list = await screen.findByTestId("lane-changes-overview");
+    const row = within(list).getByTitle("notes.txt");
+    const menu = () => within(screen.getByTestId("lane-changes-file-menu"));
+    await user.pointer({ keys: "[MouseRight]", target: row });
+    await user.click(menu().getByText("Add to .gitignore"));
+    expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "ignore", { paths: ["notes.txt"] });
+    await user.pointer({ keys: "[MouseRight]", target: row });
+    expect(menu().getByText("Add to VCS")).toBeInTheDocument();
+    // A tracked file is already in VCS, and git would not ignore it anyway.
+    await user.keyboard("{Escape}");
+    await user.pointer({
+      keys: "[MouseRight]",
+      target: within(list).getByTitle("docs/API.md"),
+    });
+    expect(menu().queryByText("Add to .gitignore")).toBeNull();
+    expect(menu().queryByText("Add to VCS")).toBeNull();
+  });
+
+  it("Show History lists one file's commits and opens the file at a commit", async () => {
+    const user = userEvent.setup();
+    render(<LaneChangesPanel laneId={7} />);
+    const list = await screen.findByTestId("lane-changes-overview");
+    await user.pointer({
+      keys: "[MouseRight]",
+      target: within(list).getByTitle("server/lib/git-ops.js"),
+    });
+    await user.click(
+      within(screen.getByTestId("lane-changes-file-menu")).getByText("Show History")
+    );
+    await waitFor(() =>
+      expect(api.lanes.gitLog).toHaveBeenLastCalledWith(7, {
+        limit: 50,
+        file: "server/lib/git-ops.js",
+      })
+    );
+    expect(screen.getByTestId("lane-changes-history-file")).toHaveTextContent(
+      "server/lib/git-ops.js"
+    );
+    await user.click(await screen.findByText("feat: the commit"));
+    await waitFor(() =>
+      expect(api.lanes.changes).toHaveBeenLastCalledWith(7, {
+        range: "commit",
+        sha: "a".repeat(40),
+        path: "server/lib/git-ops.js",
+        context: 3,
+      })
+    );
+  });
+
+  it("walks to the next file from an open one, in list order", async () => {
+    const user = userEvent.setup();
+    render(<LaneChangesPanel laneId={7} />);
+    const list = await screen.findByTestId("lane-changes-overview");
+    await user.click(within(list).getByTitle("server/lib/git-ops.js"));
+    await user.click(await screen.findByRole("button", { name: "Next file" }));
+    await waitFor(() =>
+      expect(api.lanes.changes).toHaveBeenLastCalledWith(7, {
+        range: "work",
+        path: "notes.txt",
+        context: 3,
+      })
+    );
+    expect(screen.getByRole("button", { name: "Previous file" })).toBeEnabled();
+  });
+
+  it("annotates the open file with who last changed each line", async () => {
+    vi.mocked(api.lanes.gitBlame).mockResolvedValue({
+      available: true,
+      path: "server/lib/git-ops.js",
+      commits: {},
+      lines: [],
+    });
+    const user = userEvent.setup();
+    render(<LaneChangesPanel laneId={7} />);
+    const list = await screen.findByTestId("lane-changes-overview");
+    await user.click(within(list).getByTitle("server/lib/git-ops.js"));
+    await user.click(await screen.findByRole("button", { name: "Annotate" }));
+    expect(api.lanes.gitBlame).toHaveBeenCalledWith(7, "server/lib/git-ops.js");
+    expect(screen.getByRole("button", { name: "Annotate" })).toHaveAttribute(
+      "aria-pressed",
+      "true"
+    );
   });
 
   it("disarms a pending discard when the lane changes, so one click cannot discard in another lane", async () => {
@@ -739,6 +893,132 @@ describe("LaneChangesPanel", () => {
     expect(await screen.findByTestId("lane-changes-commit-chip")).toHaveTextContent("aaaaaaa");
   });
 
+  describe("history rewrites, amend and vs base", () => {
+    const facts = (over: Record<string, unknown> = {}) => ({
+      available: true as const,
+      branch: "feat/thing",
+      head: "aaaaaaa",
+      subject: "feat: the commit",
+      dirty: 2,
+      untracked: 1,
+      files: [],
+      hasRemote: false,
+      upstream: null,
+      ahead: null,
+      behind: null,
+      base: "main",
+      ...over,
+    });
+    const commitMenu = async (user: ReturnType<typeof userEvent.setup>) => {
+      const row = await within(await screen.findByTestId("lane-changes-history")).findByText(
+        "feat: the commit"
+      );
+      await user.pointer({ keys: "[MouseRight]", target: row });
+      return screen.getByTestId("lane-changes-commit-menu");
+    };
+    const withParent = () =>
+      vi.mocked(api.lanes.gitLog).mockResolvedValue({
+        available: true,
+        commits: [
+          {
+            sha: "a".repeat(40),
+            short: "aaaaaaa",
+            subject: "feat: the commit",
+            author: "t",
+            date: "2026-09-22T01:00:00Z",
+            refs: ["HEAD -> feat/thing"],
+            parents: ["b".repeat(40)],
+          },
+        ],
+      });
+
+    it("reverts a commit and undoes the top one from the history menu", async () => {
+      withParent();
+      const user = userEvent.setup();
+      render(<LaneChangesPanel laneId={7} />);
+      await screen.findByTestId("lane-changes-overview");
+      await user.click(screen.getByRole("button", { name: "History" }));
+
+      await user.click(within(await commitMenu(user)).getByText("Revert this commit"));
+      expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "revert", { sha: "a".repeat(40) });
+
+      await user.click(within(await commitMenu(user)).getByText("Undo commit (keep changes)"));
+      await waitFor(() =>
+        expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "undo-commit", {
+          confirm: true,
+          sha: "a".repeat(40),
+        })
+      );
+    });
+
+    it("cherry-picks only from another branch's history", async () => {
+      withParent();
+      vi.mocked(api.lanes.git).mockResolvedValue(facts());
+      const user = userEvent.setup();
+      render(<LaneChangesPanel laneId={7} />);
+      await screen.findByTestId("lane-changes-overview");
+      await user.click(screen.getByRole("button", { name: "History" }));
+      expect(within(await commitMenu(user)).queryByText(/Cherry-pick/)).toBeNull();
+      await user.keyboard("{Escape}");
+
+      await user.selectOptions(await screen.findByTestId("lane-changes-history-ref"), "other");
+      await waitFor(() =>
+        expect(api.lanes.gitLog).toHaveBeenLastCalledWith(7, { limit: 50, ref: "other" })
+      );
+      await user.click(within(await commitMenu(user)).getByText("Cherry-pick onto feat/thing"));
+      expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "cherry-pick", { sha: "a".repeat(40) });
+    });
+
+    it("asks before a revert and an amend, and a No sends nothing", async () => {
+      withParent();
+      vi.mocked(confirmDialog).mockClear();
+      const user = userEvent.setup();
+      render(<LaneChangesPanel laneId={7} />);
+      await screen.findByTestId("lane-changes-overview");
+
+      vi.mocked(confirmDialog).mockResolvedValueOnce(false);
+      await user.click(screen.getByTestId("lane-changes-amend"));
+      await user.click(screen.getByRole("button", { name: "Amend" }));
+      expect(confirmDialog).toHaveBeenCalledTimes(1);
+
+      await user.click(screen.getByRole("button", { name: "History" }));
+      vi.mocked(confirmDialog).mockResolvedValueOnce(false);
+      await user.click(within(await commitMenu(user)).getByText("Revert this commit"));
+      await waitFor(() => expect(confirmDialog).toHaveBeenCalledTimes(2));
+      expect(api.lanes.gitAction).not.toHaveBeenCalled();
+    });
+
+    it("amends the last commit, keeping its message when none is typed", async () => {
+      vi.mocked(api.lanes.git).mockResolvedValue(facts());
+      const user = userEvent.setup();
+      render(<LaneChangesPanel laneId={7} />);
+      await screen.findByTestId("lane-changes-overview");
+      await user.click(screen.getByTestId("lane-changes-amend"));
+      await user.click(screen.getByRole("button", { name: "Amend" }));
+      await waitFor(() =>
+        expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "amend", {
+          sha: "aaaaaaa",
+          paths: ["server/lib/git-ops.js", "docs/API.md"],
+        })
+      );
+    });
+
+    it("names the base in full, and on the base branch itself shows no toggle at all", async () => {
+      vi.mocked(api.lanes.git).mockResolvedValue(facts());
+      const { unmount } = render(<LaneChangesPanel laneId={7} />);
+      expect(await screen.findByRole("button", { name: "Compared to main" })).toBeInTheDocument();
+      unmount();
+
+      vi.mocked(api.lanes.git).mockResolvedValue(facts({ branch: "main" }));
+      render(<LaneChangesPanel laneId={7} />);
+      await screen.findByTestId("lane-git");
+      await screen.findByTestId("lane-changes-overview");
+      expect(screen.queryByRole("button", { name: "Compared to main" })).toBeNull();
+      // A lone "Uncommitted" would be a toggle with nothing to toggle to.
+      expect(screen.queryByRole("button", { name: "Uncommitted" })).toBeNull();
+    });
+  });
+
   it("expands a folder in place, keeping its siblings visible, instead of navigating into it", async () => {
     const user = userEvent.setup();
     vi.mocked(api.lanes.gitTree).mockImplementation(async (_id, path) =>
@@ -806,7 +1086,7 @@ describe("LaneChangesPanel", () => {
     expect(screen.getByText("src")).toBeInTheDocument();
   });
 
-  it("highlights modified and untracked files in the Files tree, and folders holding them", async () => {
+  it("colours the Files tree like JetBrains: modified blue, unversioned orange, added green", async () => {
     vi.mocked(api.lanes.gitTree).mockResolvedValue({
       available: true,
       path: "",
@@ -816,6 +1096,8 @@ describe("LaneChangesPanel", () => {
         { name: "a.txt", path: "a.txt", dir: false, status: " M" },
         { name: "new.txt", path: "new.txt", dir: false, status: "??" },
         { name: "keep.txt", path: "keep.txt", dir: false },
+        { name: "add.txt", path: "add.txt", dir: false, status: "A " },
+        { name: "gone.txt", path: "gone.txt", dir: false, status: " D" },
       ],
       truncated: false,
     });
@@ -826,9 +1108,12 @@ describe("LaneChangesPanel", () => {
 
     const row = async (name: string) => (await screen.findByText(name)).closest("button")!;
     expect(await row("a.txt")).toHaveAttribute("data-tree-status", "M");
-    expect(await row("a.txt")).toHaveClass("text-status-warning");
+    expect(await row("a.txt")).toHaveClass("text-diff-mod");
     expect(await row("new.txt")).toHaveAttribute("data-tree-status", "U");
-    expect(await row("new.txt")).toHaveClass("text-status-success");
+    expect(await row("new.txt")).toHaveClass("text-kept");
+    expect(await row("add.txt")).toHaveClass("text-status-success");
+    expect(await row("gone.txt")).toHaveClass("text-fg-muted");
+    expect(await row("src")).toHaveClass("text-diff-mod");
     expect(await row("src")).toHaveAttribute("data-tree-status", "dir");
     expect(await row("keep.txt")).not.toHaveAttribute("data-tree-status");
     expect(await row("docs")).not.toHaveAttribute("data-tree-status");
@@ -937,18 +1222,6 @@ describe("LaneChangesPanel", () => {
     expect(screen.getByTestId("lane-file-editor")).toHaveValue("xy");
   });
 
-  it("unstages every staged file in one call, on the same row as Stage all and commit", async () => {
-    const user = userEvent.setup();
-    render(<LaneChangesPanel laneId={7} />);
-    await screen.findByTestId("lane-changes-overview");
-    const row = screen.getByTestId("lane-changes-actions");
-    expect(row).toContainElement(screen.getByTestId("lane-changes-commit"));
-    expect(row).toContainElement(screen.getByRole("button", { name: "Stage all (2)" }));
-
-    await user.click(screen.getByRole("button", { name: "Unstage all (1)" }));
-    expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "unstage", { paths: ["docs/API.md"] });
-  });
-
   it("switches the diff to side-by-side", async () => {
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);
@@ -1025,22 +1298,14 @@ describe("LaneChangesPanel", () => {
     );
   });
 
-  it("commits the index from the overview, never the whole tree", async () => {
+  it("cannot commit with nothing ticked", async () => {
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);
-    await screen.findByTestId("lane-changes-overview");
-
-    // The box exists only because a file is staged — with a clean index there
-    // is nothing this button could mean.
-    const box = await screen.findByTestId("lane-changes-commit");
-    await user.type(screen.getByLabelText("Commit message"), "fix: the staged half");
-    await user.click(screen.getByRole("button", { name: "Commit 1 staged" }));
-
-    expect(box).toBeInTheDocument();
-    expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "commit", {
-      message: "fix: the staged half",
-      only: "staged",
-    });
+    await screen.findByTestId("lane-changes-commit");
+    await user.type(screen.getByLabelText("Commit message"), "fix: nothing");
+    await user.click(screen.getByRole("checkbox", { name: "Tick every file in Changes" }));
+    expect(screen.getByRole("button", { name: "Commit (0)" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "Commit and Push" })).toBeDisabled();
   });
 
   it("drops a half-typed commit message on a lane switch", async () => {
@@ -1053,24 +1318,10 @@ describe("LaneChangesPanel", () => {
     expect(screen.getByLabelText("Commit message")).toHaveValue("");
   });
 
-  it("hides the commit box when nothing is staged", async () => {
-    vi.mocked(api.lanes.changes).mockResolvedValue(
-      changes({
-        files: [
-          {
-            path: "server/lib/git-ops.js",
-            status: " M",
-            untracked: false,
-            unstaged: true,
-            added: 1,
-            deleted: 0,
-            binary: false,
-          },
-        ],
-      })
-    );
+  it("hides the commit box when there is nothing to commit", async () => {
+    vi.mocked(api.lanes.changes).mockResolvedValue(changes({ files: [] }));
     render(<LaneChangesPanel laneId={7} />);
-    await screen.findByTestId("lane-changes-overview");
+    await screen.findByText("Nothing uncommitted.");
     expect(screen.queryByTestId("lane-changes-commit")).toBeNull();
   });
 
@@ -1160,22 +1411,7 @@ describe("LaneChangesPanel", () => {
       await screen.findByTestId("lane-changes-review");
     };
 
-    it("stages one hunk by its @@ line, at the context the diff was read with", async () => {
-      const user = userEvent.setup();
-      await openReview(user);
-      // Two hunks on the tracked file; the untracked one has none to act on.
-      const stage = screen.getAllByRole("button", { name: "Stage this hunk" });
-      expect(stage).toHaveLength(2);
-      await user.click(stage[1]!);
-      expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "stage-hunk", {
-        path: "server/lib/git-ops.js",
-        hunk: "@@ -9,2 +10,3 @@",
-        block: 0,
-        context: 3,
-      });
-    });
-
-    it("gives each +/- block inside ONE hunk its own bar and acts on that block only (#50)", async () => {
+    it("gives each +/- block inside ONE hunk its own bar and checkbox (#50)", async () => {
       const user = userEvent.setup();
       render(<LaneChangesPanel laneId={7} />);
       await screen.findByTestId("lane-changes-overview");
@@ -1218,13 +1454,35 @@ describe("LaneChangesPanel", () => {
         expect.stringContaining("1 of 2"),
         expect.stringContaining("2 of 2"),
       ]);
-      await user.click(screen.getAllByRole("button", { name: "Stage this hunk" })[1]!);
-      expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "stage-hunk", {
-        path: "server/lib/git-ops.js",
-        hunk: "@@ -1,4 +1,5 @@",
-        block: 1,
-        context: 3,
-      });
+      const boxes = screen.getAllByRole("checkbox", { name: "Include this change in the commit" });
+      expect(boxes).toHaveLength(2);
+      await user.click(boxes[1]!);
+      expect(boxes[0]).toBeChecked();
+      expect(boxes[1]).not.toBeChecked();
+      expect(tickOf("server/lib/git-ops.js")).toBePartiallyChecked();
+      expect(api.lanes.gitAction).not.toHaveBeenCalled();
+    });
+
+    it("commits only the ticked change blocks of a partly ticked file (hunks)", async () => {
+      const user = userEvent.setup();
+      await openReview(user);
+      // The second hunk's only block unticked: the file is partial.
+      await user.click(
+        screen.getAllByRole("checkbox", { name: "Include this change in the commit" })[1]!
+      );
+      expect(tickOf("server/lib/git-ops.js")).toBePartiallyChecked();
+      await user.click(screen.getByRole("button", { name: "Changes" }));
+      await screen.findByTestId("lane-changes-commit");
+      await user.type(screen.getByLabelText("Commit message"), "fix: half");
+      await user.click(screen.getByRole("button", { name: "Commit (1)" }));
+      await waitFor(() =>
+        expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "commit", {
+          message: "fix: half",
+          paths: [],
+          hunks: { "server/lib/git-ops.js": [{ hunk: "@@ -1,2 +1,3 @@", blocks: [0] }] },
+          context: 3,
+        })
+      );
     });
 
     it("hangs one review bar under each actionable hunk, counting them", async () => {
@@ -1266,14 +1524,18 @@ describe("LaneChangesPanel", () => {
       });
     });
 
-    it("stages a whole file from its review header without folding it", async () => {
+    it("unticks a whole file from its review header without folding it", async () => {
       const user = userEvent.setup();
       await openReview(user);
-      const [stageFile] = screen.getAllByRole("button", { name: "Stage this file" });
-      await user.click(stageFile!);
-      expect(api.lanes.gitAction).toHaveBeenCalledWith(7, "stage", {
-        paths: ["server/lib/git-ops.js"],
-      });
+      expect(screen.queryByRole("button", { name: "Stage this file" })).toBeNull();
+      await user.click(tickOf("server/lib/git-ops.js"));
+      expect(tickOf("server/lib/git-ops.js")).not.toBeChecked();
+      // Every block of it follows the file.
+      for (const box of screen.getAllByRole("checkbox", {
+        name: "Include this change in the commit",
+      }))
+        expect(box).not.toBeChecked();
+      expect(api.lanes.gitAction).not.toHaveBeenCalled();
       expect(
         screen.getByRole("button", { name: "Collapse server/lib/git-ops.js" })
       ).toBeInTheDocument();
@@ -1483,7 +1745,7 @@ describe("LaneChangesPanel", () => {
     );
     const { rerender } = render(<LaneChangesPanel laneId={7} />);
     await screen.findByTestId("lane-changes-overview");
-    const [stage] = screen.getAllByRole("button", { name: "Stage this file" });
+    const [stage] = screen.getAllByRole("button", { name: "Add to VCS" });
     await user.click(stage!);
 
     rerender(<LaneChangesPanel laneId={8} />);
@@ -1600,6 +1862,8 @@ describe("a merge in progress (issue #45)", () => {
     // Not offered as an ordinary stage: that would mark it resolved blind.
     expect(screen.getAllByText("a.txt")).toHaveLength(1);
     expect(screen.getByRole("button", { name: "Complete merge" })).toBeDisabled();
+    // A partial commit cannot finish a merge: Complete is the way out.
+    expect(screen.queryByTestId("lane-changes-commit")).toBeNull();
 
     await user.click(within(group).getByRole("button", { name: "Take theirs" }));
     await waitFor(() =>
@@ -1647,3 +1911,44 @@ describe("a merge in progress (issue #45)", () => {
     );
   });
 });
+
+describe("gitChangeFor", () => {
+  // One hunk, two change blocks three lines apart: an edit and a removal.
+  const file = {
+    path: "a.txt",
+    status: " M",
+    untracked: false,
+    added: 1,
+    deleted: 2,
+    binary: false,
+    hunks: [
+      {
+        header: "@@ -1,6 +1,5 @@",
+        context: "",
+        oldStart: 1,
+        newStart: 1,
+        lines: [
+          { type: "del" as const, oldLine: 1, newLine: null, text: "a" },
+          { type: "add" as const, oldLine: null, newLine: 1, text: "A" },
+          { type: "ctx" as const, oldLine: 2, newLine: 2, text: "b" },
+          { type: "ctx" as const, oldLine: 3, newLine: 3, text: "c" },
+          { type: "ctx" as const, oldLine: 4, newLine: 4, text: "d" },
+          { type: "del" as const, oldLine: 5, newLine: null, text: "e" },
+          { type: "ctx" as const, oldLine: 6, newLine: 5, text: "f" },
+        ],
+      },
+    ],
+  };
+
+  it("finds git's block by its line span on both sides", () => {
+    expect(gitChangeFor(file, { oldFrom: 1, oldCount: 1, newFrom: 1, newCount: 1 })?.block).toBe(0);
+    // A pure removal: matched on the old side alone.
+    expect(gitChangeFor(file, { oldFrom: 5, oldCount: 1, newFrom: 5, newCount: 0 })?.block).toBe(1);
+  });
+
+  it("finds none when the editor split the change differently", () => {
+    expect(
+      gitChangeFor(file, { oldFrom: 1, oldCount: 2, newFrom: 1, newCount: 1 })
+    ).toBeUndefined();
+  });
+});

client/src/components/lanes/__tests__/LaneDiffView.test.tsx

@@ -19,6 +19,7 @@ import {
   visibleRange,
 } from "../LaneDiffView";
 import type { LaneChangeFile } from "../../../lib/types";
+import { bandPath } from "../../../lib/diffConnectors";
 
 const FILE: LaneChangeFile = {
   path: "server/lib/git-ops.js",
@@ -59,8 +60,8 @@ describe("LaneDiffView — side by side", () => {
     expect(screen.getByTestId("lane-diff-split-right").className).toContain("overflow-auto");
   });
 
-  it("keeps an empty filler row one line tall, so the columns stay in step", () => {
-    // Two lines removed, none added: the right column's two rows are fillers.
+  it("pads the shorter side only at the hunk's end, each pad one line tall", () => {
+    // Two lines removed, none added: the right column's two rows are padding.
     const file = fileWith([
       { type: "del", oldLine: 1, newLine: null, text: "gone one" },
       { type: "del", oldLine: 2, newLine: null, text: "gone two" },
@@ -72,7 +73,39 @@ describe("LaneDiffView — side by side", () => {
         .querySelectorAll<HTMLElement>("div.flex.w-max"),
     ];
     expect(fillers).toHaveLength(2);
-    for (const row of fillers) expect(row.style.minHeight).toBe("16px");
+    for (const row of fillers) expect(row.style.height).toBe("16px");
+  });
+
+  it("packs each side's own lines, JetBrains-style, and joins every block with a band", () => {
+    const file = fileWith([
+      { type: "ctx", oldLine: 1, newLine: 1, text: "top" },
+      { type: "del", oldLine: 2, newLine: null, text: "old a" },
+      { type: "del", oldLine: 3, newLine: null, text: "old b" },
+      { type: "add", oldLine: null, newLine: 2, text: "new a" },
+      { type: "ctx", oldLine: 4, newLine: 3, text: "mid" },
+      { type: "add", oldLine: null, newLine: 4, text: "extra" },
+      { type: "ctx", oldLine: 5, newLine: 5, text: "end" },
+    ]);
+    render(<LaneDiffView file={file} layout="split" />);
+    const texts = (id: string) =>
+      [...screen.getByTestId(id).querySelectorAll<HTMLElement>("div.flex.w-max")].map((r) =>
+        r.textContent?.replace(/^\d+/, "")
+      );
+    // No gap inside a hunk: a side's lines follow one another (5 each, no pad).
+    expect(texts("lane-diff-split-left")).toEqual(["top", "old a", "old b", "mid", "end"]);
+    expect(texts("lane-diff-split-right")).toEqual(["top", "new a", "mid", "extra", "end"]);
+    // Two blocks, two bands: rows start under the one-row hunk header.
+    const bands = [
+      ...screen.getByTestId("lane-diff-connectors").querySelectorAll<SVGPathElement>("path"),
+    ];
+    expect(bands.map((b) => b.dataset.kind)).toEqual(["mod", "add"]);
+    expect(bands[0]!.getAttribute("d")).toBe(
+      bandPath(36, 2 * ROW_PX, 4 * ROW_PX, 2 * ROW_PX, 3 * ROW_PX)
+    );
+    // The insertion is a wedge from the left's point between "mid" and "end".
+    expect(bands[1]!.getAttribute("d")).toBe(
+      bandPath(36, 5 * ROW_PX, 5 * ROW_PX, 4 * ROW_PX, 5 * ROW_PX)
+    );
   });
 
   it("caps a review diff only when it windows; the single-file view fills its parent", () => {
@@ -414,8 +447,8 @@ describe("LaneDiffView — windowing", () => {
     expect(l.length).toBeLessThan(300);
     expect(l).toHaveLength(r.length);
     expect(right.textContent).toContain("line 2001;");
-    // same rows: the right column's add has its filler row on the left
-    expect(left.textContent).toContain("line 2000;");
+    // Packed: the left holds only the context lines, so it runs twice as far.
+    expect(left.textContent).toContain("line 4000;");
   });
 
   it("windows a whole-file read too", () => {

client/src/components/lanes/__tests__/LaneGitBar.test.tsx

@@ -14,6 +14,7 @@ import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { LaneGitBar } from "../LaneGitBar";
 import { api } from "../../../lib/api";
+import { confirmDialog } from "../../../lib/confirm";
 import type { LaneGitFacts } from "../../../lib/types";
 
 // A merge asks through the themed confirm (its host lives in App): yes.
@@ -129,6 +130,40 @@ describe("LaneGitBar", () => {
     expect(onChanged).toHaveBeenCalled();
   });
 
+  it("asks before every outward or ref-deleting write, and a No sends nothing", async () => {
+    const user = userEvent.setup();
+    vi.mocked(confirmDialog).mockResolvedValueOnce(false);
+    const { rerender } = render(
+      <LaneGitBar laneId={3} git={facts({ ahead: 2 })} onChanged={vi.fn()} />
+    );
+    await user.click(screen.getByRole("button", { name: /Push/ }));
+    expect(confirmDialog).toHaveBeenLastCalledWith(
+      expect.objectContaining({ message: expect.stringContaining("2 commit") })
+    );
+    expect(api.lanes.gitAction).not.toHaveBeenCalled();
+
+    // A Yes goes through.
+    await user.click(screen.getByRole("button", { name: /Push/ }));
+    await waitFor(() => expect(api.lanes.gitAction).toHaveBeenCalledWith(3, "push", {}));
+
+    vi.mocked(api.lanes.gitAction).mockClear();
+    vi.mocked(confirmDialog).mockResolvedValueOnce(false);
+    rerender(
+      <LaneGitBar
+        laneId={3}
+        git={facts({ hasRemote: false, upstream: null, ahead: null, behind: null })}
+        onChanged={vi.fn()}
+      />
+    );
+    await user.click(screen.getByRole("button", { name: "Publish…" }));
+    await user.type(screen.getByLabelText(/Remote URL/), "git@host:o/r.git");
+    await user.click(screen.getByRole("button", { name: "Publish" }));
+    expect(confirmDialog).toHaveBeenLastCalledWith(
+      expect.objectContaining({ message: expect.stringContaining("git@host:o/r.git") })
+    );
+    expect(api.lanes.gitAction).not.toHaveBeenCalled();
+  });
+
   it("calls a first push of a branch with no upstream 'Publish branch'", async () => {
     const user = userEvent.setup();
     render(

client/src/components/lanes/__tests__/WorkspaceHome.test.tsx

@@ -2,8 +2,8 @@
  * @file WorkspaceHome.test.tsx
  * @description The workspace home: a new session starts in the first free
  * pane slot and opens it, on the AI tool picked for it (the workspace's by
- * default), AI and Model in the box and AI Router / Permission / Worktree
- * under it (the router's models on a router), all-busy is refused, Recents open a live pane or the
+ * default), AI and Model in the box and AI Proxy / Permission / Worktree
+ * under it (the proxy's models on a proxy), all-busy is refused, Recents open a live pane or the
  * transcript (never a resume), instructions save, context files upload and
  * remove, a folder is added with the repo's untracked worktrees suggested
  * (minus hidden sources), an unsupported tool is said so, and memory opens
@@ -12,7 +12,7 @@
  */
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { render, screen, waitFor, within } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { MemoryRouter, Route, Routes, useLocation } from "react-router-dom";
 import type { Lane, Session } from "../../../lib/types";
@@ -117,7 +117,7 @@ vi.mock("../../../lib/api", async (importOriginal) => {
         })),
       },
       aiTools: { list: vi.fn(async () => ({ tools: [], default: "claude" })), iconUrl: () => "" },
-      aiRouters: { list: vi.fn(async () => ({ items: [] })) },
+      aiProxies: { list: vi.fn(async () => ({ items: [] })) },
     },
   };
 });
@@ -193,7 +193,9 @@ describe("freeSlot / paneRunId", () => {
   it("picks the first slot no live run of this lane holds", () => {
     expect(freeSlot(1, [])).toBe(0);
     expect(freeSlot(1, runs)).toBe(1);
-    const all = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].map((slot) => ({ laneId: 1, slot, status: "running" }) as RunHandle);
+    const all = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].map(
+      (slot) => ({ laneId: 1, slot, status: "running" }) as RunHandle
+    );
     expect(freeSlot(1, all)).toBeNull();
     expect(freeSlot(1, all.slice(0, 4))).toBe(4);
     expect(freeSlot(2, all)).toBe(0);
@@ -222,7 +224,24 @@ describe("WorkspaceHome", () => {
     );
   });
 
-  it("keeps AI and Model (with effort) in the box, Router/Permission/Worktree under it", async () => {
+  it("keeps a half-typed prompt per workspace across a remount, and drops it once sent", async () => {
+    const user = userEvent.setup();
+    const first = renderHome();
+    await screen.findByTestId("workspace-recent-s-live");
+    await user.type(screen.getByLabelText("How can I help you today?"), "long draft");
+    first.unmount();
+    const other = renderHome(lane({ id: 2 }));
+    await screen.findByTestId("workspace-recent-s-live");
+    expect(screen.getByLabelText("How can I help you today?")).toHaveValue("");
+    other.unmount();
+    renderHome();
+    await screen.findByTestId("workspace-recent-s-live");
+    expect(screen.getByLabelText("How can I help you today?")).toHaveValue("long draft");
+    await user.click(screen.getByTestId("workspace-home-start"));
+    await waitFor(() => expect(localStorage.getItem("agenthub.workspace.draft.1")).toBeNull());
+  });
+
+  it("keeps AI and Model (with effort) in the box, Proxy/Permission/Worktree under it", async () => {
     renderHome();
     await screen.findByTestId("workspace-recent-s-live");
     const labels = (id: string) =>
@@ -233,7 +252,7 @@ describe("WorkspaceHome", () => {
       ].map((x) => x.getAttribute("aria-label"));
     expect(labels("workspace-home-composer")).toEqual(["AI", "model"]);
     expect(labels("workspace-home-options")).toEqual([
-      "AI Router",
+      "AI Proxy",
       "Permission mode",
       expect.stringContaining("own git worktree"),
     ]);
@@ -244,8 +263,8 @@ describe("WorkspaceHome", () => {
     vi.mocked(api.aiTools.list).mockResolvedValue({
       default: "claude",
       tools: [
-        { id: "claude", label: "Claude Code", launcher: "claude", routerCapable: true },
-        { id: "codex", label: "Codex", launcher: "codex", routerCapable: true, bypass: true },
+        { id: "claude", label: "Claude Code", launcher: "claude", proxyCapable: true },
+        { id: "codex", label: "Codex", launcher: "codex", proxyCapable: true, bypass: true },
         { id: "cursor", label: "Cursor CLI", installed: false, enabled: true },
       ].map((x) => ({ installed: true, enabled: true, ...x })),
     } as never);
@@ -270,9 +289,9 @@ describe("WorkspaceHome", () => {
     __resetAiTools();
   });
 
-  it("offers the router's models on a router, and sends the router", async () => {
-    localStorage.setItem("agenthub.session.router", "glm");
-    vi.mocked(api.aiRouters.list).mockResolvedValueOnce({
+  it("offers the proxy's models on a proxy, and sends the proxy", async () => {
+    localStorage.setItem("agenthub.session.proxy", "glm");
+    vi.mocked(api.aiProxies.list).mockResolvedValueOnce({
       items: [
         { name: "native", label: "Native", builtin: true, models: {} },
         {
@@ -297,7 +316,7 @@ describe("WorkspaceHome", () => {
     expect(api.lanes.action).toHaveBeenCalledWith(
       1,
       "start",
-      expect.objectContaining({ router: "glm" })
+      expect.objectContaining({ proxy: "glm" })
     );
   });
 
@@ -319,6 +338,21 @@ describe("WorkspaceHome", () => {
     });
   });
 
+  it("opens a terminal tab at once from the AI menu, without a prompt", async () => {
+    const user = userEvent.setup();
+    renderHome();
+    await screen.findByTestId("workspace-recent-s-old");
+    const ai = screen.getByTestId("workspace-home-tool");
+    await user.click(within(ai).getByRole("button"));
+    await user.click(screen.getByRole("option", { name: /Open terminal/ }));
+    expect(api.lanes.action).toHaveBeenCalledWith(1, "start", { slot: "auto", shell: true });
+    await waitFor(() =>
+      expect(screen.getByTestId("where").textContent).toMatch(/^\/workspace\?lane=1&run=/)
+    );
+    // The AI picked for the next prompt is untouched.
+    expect(within(ai).getByRole("button")).not.toHaveTextContent(/terminal/i);
+  });
+
   it("says so when the server finds all ten sessions in use", async () => {
     vi.mocked(api.lanes.action).mockRejectedValueOnce(
       Object.assign(new Error("every tab of this workspace is busy"), { code: "ERUNLIVE" })
@@ -363,6 +397,24 @@ describe("WorkspaceHome", () => {
     expect(api.sessions.patch).toHaveBeenCalledWith("s-old", { archived: false });
   });
 
+  it("shows more recents a page at a time, and collapses them again", async () => {
+    vi.mocked(api.sessions.list).mockImplementation(async (params) => {
+      const all = (params as { archived?: boolean }).archived
+        ? []
+        : Array.from({ length: 35 }, (_, i) => ({ ...sessions[1]!, id: `s-${i}` }));
+      const limit = (params as { limit?: number }).limit ?? 30;
+      return { sessions: all.slice(0, limit), total: all.length, limit, offset: 0 };
+    });
+    const user = userEvent.setup();
+    renderHome();
+    await user.click(await screen.findByTestId("workspace-recents-more"));
+    expect(api.sessions.list).toHaveBeenCalledWith({ lane: 1, archived: false, limit: 60 });
+    await user.click(await screen.findByTestId("workspace-recents-less"));
+    expect(api.sessions.list).toHaveBeenLastCalledWith({ lane: 1, archived: false, limit: 30 });
+    expect(await screen.findByTestId("workspace-recents-more")).toBeInTheDocument();
+    expect(screen.queryByTestId("workspace-recents-less")).toBeNull();
+  });
+
   it("opens a live recent's pane and an ended one's conversation, resuming nothing", async () => {
     const user = userEvent.setup();
     renderHome();
@@ -435,6 +487,13 @@ describe("WorkspaceHome", () => {
     const file = new File(["# notes"], "notes.md", { type: "text/markdown" });
     await user.upload(screen.getByTestId("workspace-file-input"), file);
     expect(api.lanes.addFile).toHaveBeenCalledWith(1, file);
+    const a = new File(["a"], "a.csv", { type: "text/csv" });
+    const b = new File(["b"], "b.log", { type: "" });
+    fireEvent.drop(screen.getByTestId("workspace-context-files"), {
+      dataTransfer: { types: ["Files"], files: [a, b] },
+    });
+    await waitFor(() => expect(api.lanes.addFile).toHaveBeenCalledWith(1, b));
+    expect(api.lanes.addFile).toHaveBeenCalledWith(1, a);
     await user.click(screen.getByRole("button", { name: "Remove spec.pdf" }));
     expect(api.lanes.removeSource).toHaveBeenCalledWith(1, 7);
   });

client/src/components/lanes/__tests__/sessionPaths.test.ts

@@ -0,0 +1,33 @@
+/**
+ * @file Tests that a session finds its workspace and its `claude --worktree`
+ * name by folder on Windows paths (`D:\…`) as well as POSIX ones — the
+ * transcript page's Resume/Fork/Open pane hid on Windows when they matched
+ * on "/" only.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect } from "vitest";
+import type { Lane, Session } from "../../../lib/types";
+import { owningLane } from "../SessionResumeButton";
+import { sessionWorktreeName } from "../WorkspaceSessionList";
+
+const lane = (id: number, cwd: string) => ({ id, cwd, tool: "claude" }) as Lane;
+
+describe("session paths", () => {
+  it("finds the deepest owning workspace with either separator", () => {
+    const lanes = [lane(1, "D:\\Project"), lane(2, "D:\\Project\\Hobby\\"), lane(3, "/home/u/app")];
+    expect(owningLane("D:\\Project\\Hobby\\tri-vi-portfolio", "claude", lanes)?.id).toBe(2);
+    expect(owningLane("D:\\Project\\Hobby", "claude", lanes)?.id).toBe(2);
+    expect(owningLane("D:\\ProjectX", "claude", lanes)).toBeNull();
+    expect(owningLane("/home/u/app/src", "claude", lanes)?.id).toBe(3);
+  });
+
+  it("reads a worktree name from a Windows or POSIX session folder", () => {
+    const at = (cwd: string) => ({ cwd }) as Session;
+    expect(
+      sessionWorktreeName(lane(1, "D:\\repo"), at("D:\\repo\\.claude\\worktrees\\fix-a"))
+    ).toBe("fix-a");
+    expect(sessionWorktreeName(lane(1, "/r"), at("/r/.claude/worktrees/fix-b/"))).toBe("fix-b");
+    expect(sessionWorktreeName(lane(1, "D:\\repo"), at("D:\\repo\\"))).toBeNull();
+  });
+});

client/src/components/lanes/splitDiff.ts

@@ -0,0 +1,425 @@
+/**
+ * @file The file editor's side-by-side layout, JetBrains-shaped: the original
+ * (read-only, left) and the working file (editable, right) are two
+ * CodeMirror views in their OWN scrollers, with no padding to line them up —
+ * each shows its real lines — and the gutter between them draws, for every
+ * changed block, a curved band joining its lines on the left to its lines on
+ * the right (`lib/diffConnectors.ts`), with a » that reverts the block.
+ * Scrolling either side scrolls the other to the matching line (`mapLine`:
+ * 1:1 outside a block, proportional inside one).
+ *
+ * What @codemirror/merge's MergeView gave the old layout is kept, by its own
+ * public pieces: the chunks are `Chunk.build` at mount and `Chunk.updateB` on
+ * every edit of the right side; the changed-line, changed-text and gutter
+ * classes, the editor-root `cm-merge-a`/`cm-merge-b` classes, the folded
+ * unchanged stretches (opened on both sides at once) and the revert's text
+ * rule are ported from it, so DiffEditor's theme and colouring apply as before.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import {
+  EditorState,
+  RangeSet,
+  StateEffect,
+  StateField,
+  Text,
+  type Extension,
+} from "@codemirror/state";
+import {
+  Decoration,
+  EditorView,
+  GutterMarker,
+  WidgetType,
+  gutterLineClass,
+  type DecorationSet,
+} from "@codemirror/view";
+import { Chunk, getChunks } from "@codemirror/merge";
+import { bandPath, mapLine, type Span } from "../../lib/diffConnectors";
+
+/** The chunks a side carries, the side it is, and (right side) the original. */
+type SplitState = { chunks: readonly Chunk[]; side: "a" | "b"; orig: Text | null };
+
+const setChunks = StateEffect.define<readonly Chunk[]>();
+const uncollapse = StateEffect.define<number>();
+
+/** Each side's chunks. The right side recomputes them as it is edited; the
+ *  left, read-only, is handed the new list (`setChunks`). */
+const splitField = StateField.define<SplitState>({
+  create: () => ({ chunks: [], side: "b", orig: null }),
+  update(v, tr) {
+    for (const e of tr.effects) if (e.is(setChunks)) return { ...v, chunks: e.value };
+    if (v.orig && tr.docChanged) {
+      return { ...v, chunks: Chunk.updateB(v.chunks, v.orig, tr.state.doc, tr.changes) };
+    }
+    return v;
+  },
+});
+
+/** The chunks and side of an editor in either merge layout — unified (the
+ *  merge package's own state) or this split. */
+export function chunksOf(
+  state: EditorState
+): { chunks: readonly Chunk[]; side: "a" | "b" | null } | null {
+  return getChunks(state) ?? state.field(splitField, false) ?? null;
+}
+
+const changedLine = Decoration.line({ class: "cm-changedLine" });
+const changedText = Decoration.mark({ class: "cm-changedText" });
+const changedGutter = new (class extends GutterMarker {
+  override elementClass = "cm-changedLineGutter";
+})();
+
+/** The lines (and, inside them, the changed spans) of this side's chunks. */
+function changedRanges(state: EditorState) {
+  const { chunks, side } = state.field(splitField);
+  const doc = state.doc;
+  const lines: number[] = [];
+  const spans: [number, number][] = [];
+  for (const c of chunks) {
+    const [from, to] = side === "a" ? [c.fromA, c.toA] : [c.fromB, c.toB];
+    if (from >= to) continue;
+    const last = doc.lineAt(Math.min(to - 1, doc.length)).number;
+    for (let n = doc.lineAt(from).number; n <= last; n += 1) {
+      const line = doc.line(n);
+      lines.push(line.from);
+      for (const ch of c.changes) {
+        const s = Math.max(line.from, from + (side === "a" ? ch.fromA : ch.fromB));
+        const e = Math.min(line.to, from + (side === "a" ? ch.toA : ch.toB));
+        if (s < e) spans.push([s, e]);
+      }
+    }
+  }
+  return { lines, spans };
+}
+
+const chunkDecorations = EditorView.decorations.compute([splitField], (state) => {
+  const { lines, spans } = changedRanges(state);
+  return Decoration.set(
+    [...lines.map((p) => changedLine.range(p)), ...spans.map(([s, e]) => changedText.range(s, e))],
+    true
+  );
+});
+const chunkGutter = gutterLineClass.compute([splitField], (state) =>
+  RangeSet.of(
+    changedRanges(state).lines.map((p) => changedGutter.range(p)),
+    true
+  )
+);
+
+/** The other side's editor, for a fold opened on one side to open on both. */
+const siblings = new WeakMap<EditorView, EditorView>();
+
+/** `pos` on one side, moved past the chunks before it to the other (ported). */
+function mapPos(pos: number, chunks: readonly Chunk[], isA: boolean) {
+  let ours = 0;
+  let theirs = 0;
+  for (const c of chunks) {
+    if ((isA ? c.fromA : c.fromB) >= pos) break;
+    [ours, theirs] = isA ? [c.toA, c.toB] : [c.toB, c.toA];
+  }
+  return theirs + (pos - ours);
+}
+
+class CollapseWidget extends WidgetType {
+  constructor(readonly lines: number) {
+    super();
+  }
+  override eq(o: CollapseWidget) {
+    return this.lines === o.lines;
+  }
+  toDOM(view: EditorView) {
+    const el = document.createElement("div");
+    el.className = "cm-collapsedLines";
+    el.textContent = view.state.phrase("$ unchanged lines", this.lines);
+    el.addEventListener("click", (e) => {
+      const pos = view.posAtDOM(e.target as Node);
+      view.dispatch({ effects: uncollapse.of(pos) });
+      const { chunks, side } = view.state.field(splitField);
+      siblings.get(view)?.dispatch({ effects: uncollapse.of(mapPos(pos, chunks, side === "a")) });
+    });
+    return el;
+  }
+  override ignoreEvent(e: Event) {
+    return e instanceof MouseEvent;
+  }
+  override get estimatedHeight() {
+    return 27;
+  }
+}
+
+/** The folded unchanged stretches: built once at mount, then only mapped,
+ *  opened by a click, and dropped where an edit grows a chunk into them. */
+const collapsedField = StateField.define<DecorationSet>({
+  create: () => Decoration.none,
+  update(deco, tr) {
+    deco = deco.map(tr.changes);
+    for (const e of tr.effects) {
+      if (e.is(uncollapse)) deco = deco.update({ filter: (from) => from !== e.value });
+    }
+    const { chunks, side } = tr.state.field(splitField);
+    if (deco.size && chunks !== tr.startState.field(splitField).chunks) {
+      const touching: number[] = [];
+      for (const c of chunks) {
+        deco.between(side === "a" ? c.fromA : c.fromB, side === "a" ? c.toA : c.toB, (from) => {
+          touching.push(from);
+        });
+      }
+      if (touching.length) deco = deco.update({ filter: (from) => !touching.includes(from) });
+    }
+    return deco;
+  },
+  provide: (f) => EditorView.decorations.from(f),
+});
+
+function buildCollapsed(state: EditorState, margin: number, minLines: number) {
+  const { chunks, side } = state.field(splitField);
+  const doc = state.doc;
+  const out = [];
+  let prev = 1;
+  for (let i = 0; ; i += 1) {
+    const c = i < chunks.length ? chunks[i]! : null;
+    const from = i ? prev + margin : 1;
+    const to = c ? doc.lineAt(side === "a" ? c.fromA : c.fromB).number - 1 - margin : doc.lines;
+    const lines = to - from + 1;
+    if (lines >= minLines) {
+      out.push(
+        Decoration.replace({ widget: new CollapseWidget(lines), block: true }).range(
+          doc.line(from).from,
+          doc.line(to).to
+        )
+      );
+    }
+    if (!c) break;
+    prev = doc.lineAt(Math.min(doc.length, side === "a" ? c.toA : c.toB)).number;
+  }
+  return Decoration.set(out);
+}
+
+/** A chunk side as 0-based half-open lines; an empty side is the point
+ *  before the line it sits above (past the end: after the last line). */
+function sideLines(doc: Text, from: number, to: number): [number, number] {
+  const first = from > doc.length ? doc.lines : doc.lineAt(from).number - 1;
+  if (from >= to) return [first, first];
+  return [first, doc.lineAt(Math.min(to - 1, doc.length)).number];
+}
+
+function spansOf(chunks: readonly Chunk[], a: Text, b: Text): Span[] {
+  return chunks.map((c) => {
+    const [a0, a1] = sideLines(a, c.fromA, c.toA);
+    const [b0, b1] = sideLines(b, c.fromB, c.toB);
+    return { a0, a1, b0, b1 };
+  });
+}
+
+/** Where the document starts inside the view's scroll content. */
+const docOffset = (v: EditorView) =>
+  v.documentTop - v.scrollDOM.getBoundingClientRect().top + v.scrollDOM.scrollTop;
+
+/** The fractional line at the top of the view (a folded stretch spreads its
+ *  height over the lines it hides). */
+function topLine(v: EditorView) {
+  const h = Math.max(0, v.scrollDOM.scrollTop - docOffset(v));
+  const blk = v.lineBlockAtHeight(h);
+  const first = v.state.doc.lineAt(blk.from).number - 1;
+  const n = v.state.doc.lineAt(blk.to).number - first;
+  const frac = blk.height > 0 ? Math.min(1, Math.max(0, (h - blk.top) / blk.height)) : 0;
+  return first + frac * n;
+}
+
+/** Document y of a fractional line (0-based). */
+function yOf(v: EditorView, line: number) {
+  const doc = v.state.doc;
+  if (line >= doc.lines) return v.lineBlockAt(doc.length).bottom;
+  const blk = v.lineBlockAt(doc.line(Math.max(0, Math.floor(line)) + 1).from);
+  const first = doc.lineAt(blk.from).number - 1;
+  const n = doc.lineAt(blk.to).number - first;
+  return blk.top + ((line - first) / n) * blk.height;
+}
+
+/** The gutter's width: room for an S-curve and the » under it. */
+const GUTTER_PX = 40;
+const BAND: Record<"add" | "del" | "mod", string> = {
+  add: "fill-status-success/20 stroke-status-success/60",
+  del: "fill-status-danger/20 stroke-status-danger/60",
+  mod: "fill-diff-mod/20 stroke-diff-mod/60",
+};
+const SVG = "http://www.w3.org/2000/svg";
+
+export function splitDiff({
+  parent,
+  original,
+  value,
+  extA,
+  extB,
+  collapse,
+  revertLabel,
+}: {
+  parent: HTMLElement;
+  original: string;
+  value: string;
+  /** Each side's own extensions (DiffEditor's colours, keymaps, …). */
+  extA: Extension[];
+  extB: Extension[];
+  collapse?: { margin: number; minSize: number };
+  revertLabel: string;
+}): { a: EditorView; b: EditorView; destroy: () => void } {
+  const origDoc = Text.of(original.split(/\r?\n/));
+  const chunks0 = Chunk.build(origDoc, Text.of(value.split(/\r?\n/)));
+
+  const root = parent.appendChild(document.createElement("div"));
+  root.className = "flex h-full min-h-0";
+  const pane = () => {
+    const el = document.createElement("div");
+    el.className = "h-full min-w-0 flex-1";
+    return el;
+  };
+  const paneA = root.appendChild(pane());
+  const gutter = root.appendChild(document.createElement("div"));
+  gutter.className =
+    "cm-merge-revert relative h-full shrink-0 overflow-hidden border-x border-border-light bg-surface-1";
+  gutter.style.width = `${GUTTER_PX}px`;
+  gutter.dataset.testid = "lane-editor-connectors";
+  const svg = gutter.appendChild(document.createElementNS(SVG, "svg"));
+  svg.setAttribute("class", "absolute inset-0 h-full w-full");
+  const buttons = gutter.appendChild(document.createElement("div"));
+  const paneB = root.appendChild(pane());
+
+  let frame = 0;
+  const draw = () => {
+    if (frame) return;
+    const run = () => {
+      frame = 0;
+      paint();
+    };
+    frame =
+      typeof requestAnimationFrame === "function"
+        ? requestAnimationFrame(run)
+        : window.setTimeout(run);
+  };
+
+  const side = (s: "a" | "b"): Extension[] => [
+    splitField.init(() => ({ chunks: chunks0, side: s, orig: s === "b" ? origDoc : null })),
+    chunkDecorations,
+    chunkGutter,
+    EditorView.editorAttributes.of({ class: `cm-merge-${s}` }),
+    ...(collapse
+      ? [collapsedField.init((st) => buildCollapsed(st, collapse.margin, collapse.minSize))]
+      : []),
+    EditorView.updateListener.of((u) => {
+      if (u.docChanged || u.geometryChanged || u.viewportChanged) draw();
+    }),
+  ];
+
+  const a = new EditorView({
+    parent: paneA,
+    state: EditorState.create({ doc: origDoc, extensions: [...side("a"), ...extA] }),
+  });
+  const b = new EditorView({
+    parent: paneB,
+    state: EditorState.create({
+      doc: value,
+      extensions: [
+        ...side("b"),
+        ...extB,
+        // The left side is told the chunks the right side's edit produced.
+        EditorView.updateListener.of((u) => {
+          const now = u.state.field(splitField).chunks;
+          if (now !== u.startState.field(splitField).chunks)
+            a.dispatch({ effects: setChunks.of(now) });
+        }),
+      ],
+    }),
+  });
+  siblings.set(a, b);
+  siblings.set(b, a);
+
+  const spans = () => spansOf(b.state.field(splitField).chunks, a.state.doc, b.state.doc);
+
+  // Scrolling one side scrolls the other to the line beside it. A scroll we
+  // caused comes back as the other side's own event: `echo` holds where we
+  // put it, so that event is recognised and not mirrored back.
+  const echo = { a: -1, b: -1 };
+  const follow = (from: "a" | "b") => () => {
+    const [src, dst, to] = from === "a" ? [a, b, "b" as const] : [b, a, "a" as const];
+    if (Math.abs(src.scrollDOM.scrollTop - echo[from]) < 1) {
+      echo[from] = -1;
+      draw();
+      return;
+    }
+    const line = mapLine(topLine(src), spans(), from === "a");
+    const target = Math.round(yOf(dst, line) + docOffset(dst));
+    const before = dst.scrollDOM.scrollTop;
+    dst.scrollDOM.scrollTop = target;
+    if (dst.scrollDOM.scrollTop !== before) echo[to] = dst.scrollDOM.scrollTop;
+    draw();
+  };
+  const onA = follow("a");
+  const onB = follow("b");
+  a.scrollDOM.addEventListener("scroll", onA, { passive: true });
+  b.scrollDOM.addEventListener("scroll", onB, { passive: true });
+  const resize = typeof ResizeObserver === "function" ? new ResizeObserver(draw) : null;
+  resize?.observe(root);
+
+  // » puts the original block back on the right (the merge package's rule:
+  // a non-empty source brings its line break unless it ends the document).
+  buttons.addEventListener("mousedown", (e) => {
+    const i = Number((e.target as HTMLElement).closest<HTMLElement>("[data-chunk]")?.dataset.chunk);
+    const c = b.state.field(splitField).chunks[i];
+    if (!c) return;
+    let insert = a.state.sliceDoc(c.fromA, Math.max(c.fromA, c.toA - 1));
+    if (c.fromA !== c.toA && c.toB <= b.state.doc.length) insert += a.state.lineBreak;
+    b.dispatch({
+      changes: { from: c.fromB, to: Math.min(b.state.doc.length, c.toB), insert },
+      userEvent: "revert",
+    });
+    e.preventDefault();
+  });
+
+  function paint() {
+    const g = gutter.getBoundingClientRect();
+    const height = gutter.clientHeight;
+    const ya = (l: number) => a.documentTop - g.top + yOf(a, l);
+    const yb = (l: number) => b.documentTop - g.top + yOf(b, l);
+    const paths: SVGPathElement[] = [];
+    const btns: HTMLButtonElement[] = [];
+    spans().forEach((s, i) => {
+      const [y0, y1, z0, z1] = [ya(s.a0), ya(s.a1), yb(s.b0), yb(s.b1)];
+      // Off screen on both sides: nothing to draw (no layout = draw all).
+      if (height > 0 && (Math.max(y1, z1) < 0 || Math.min(y0, z0) > height)) return;
+      const kind = s.a0 === s.a1 ? "add" : s.b0 === s.b1 ? "del" : "mod";
+      const p = document.createElementNS(SVG, "path");
+      p.setAttribute("d", bandPath(GUTTER_PX, y0, y1, z0, z1));
+      p.setAttribute("class", BAND[kind]);
+      p.setAttribute("vector-effect", "non-scaling-stroke");
+      p.dataset.kind = kind;
+      paths.push(p);
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.textContent = "»";
+      btn.title = revertLabel;
+      btn.setAttribute("aria-label", revertLabel);
+      btn.dataset.chunk = String(i);
+      btn.className =
+        "absolute left-0.5 z-10 rounded px-0.5 text-[11px] leading-none text-fg-secondary hover:bg-surface-3 hover:text-fg-primary";
+      btn.style.top = `${Math.max(0, y0) + 1}px`;
+      btns.push(btn);
+    });
+    svg.replaceChildren(...paths);
+    buttons.replaceChildren(...btns);
+  }
+  draw();
+
+  return {
+    a,
+    b,
+    destroy: () => {
+      if (frame)
+        (typeof cancelAnimationFrame === "function" ? cancelAnimationFrame : clearTimeout)(frame);
+      resize?.disconnect();
+      a.scrollDOM.removeEventListener("scroll", onA);
+      b.scrollDOM.removeEventListener("scroll", onB);
+      a.destroy();
+      b.destroy();
+      root.remove();
+    },
+  };
+}

client/src/components/lanes/startSession.ts

@@ -9,7 +9,7 @@
 
 import i18n from "../../i18n";
 import { api, type RunHandle } from "../../lib/api";
-import { MAX_SLOTS } from "../../lib/paneLayout";
+import { MAX_SLOTS, slotOfKey } from "../../lib/paneLayout";
 
 /** The tmux session a pane slot of a lane owns (server/lib/pty-run.js). */
 export function paneRunId(laneId: number, slot: number): string {
@@ -58,7 +58,9 @@ export async function startInFreeTabDetailed(
 /** The first pane slot with no live run, or null when all ten are busy. */
 export function freeSlot(laneId: number, runs: RunHandle[]): number | null {
   const busy = new Set(
-    runs.filter((r) => r.laneId === laneId && r.status === "running").map((r) => r.slot ?? 0)
+    runs
+      .filter((r) => r.laneId === laneId && r.status === "running")
+      .map((r) => slotOfKey(r.slot ?? 0))
   );
   for (let s = 0; s < MAX_SLOTS; s++) if (!busy.has(s)) return s;
   return null;

client/src/components/onboarding/OnboardingTour.tsx

@@ -0,0 +1,239 @@
+/**
+ * @file OnboardingTour.tsx
+ * @description The step-by-step spotlight tour after the first-run setup
+ * (docs/plans/onboarding): it dims the page around ONE real control and says
+ * what to do with it — Add workspace → the folder → Add → the prompt box →
+ * the live session → done. The overlay never takes a click (the user works
+ * the real UI); a step moves on when what it asked for has happened (the
+ * dialog opened, the workspace exists, the session started), and steps back
+ * when the user backed out (the dialog closed with nothing made). Targets are
+ * existing `data-testid`s plus `data-tour` marks in AddLaneModal and
+ * FolderBrowseModal. The
+ * step reached is `localStorage["agenthub.tour"]`, so it is synced to the
+ * account and survives a reload; `done` ends it.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { useTranslation } from "react-i18next";
+import { useLocation, useNavigate } from "react-router-dom";
+
+const KEY = "agenthub.tour";
+const EVENT = "agenthub-tour";
+const POLL_MS = 250;
+
+type StepId = "add" | "folder" | "create" | "prompt" | "session" | "finish";
+const ORDER: StepId[] = ["add", "folder", "create", "prompt", "session", "finish"];
+
+const $ = (sel: string) => document.querySelector(sel);
+/** An element that is on screen (a console collapsed with CSS has no box). */
+function shown(sel: string): Element | null {
+  const el = $(sel);
+  if (!el) return null;
+  const r = el.getBoundingClientRect();
+  return r.width > 0 && r.height > 0 ? el : null;
+}
+
+const modalOpen = () => !!$('[data-tour="add-lane"]');
+const composer = () => shown('[data-testid="workspace-home-composer"]');
+const sessionLive = () =>
+  !!new URLSearchParams(window.location.search).get("run") && !!shown('[data-testid="pane-grid"]');
+
+/** Where each step points, and what moves it on (or back). */
+const STEPS: Record<
+  StepId,
+  { target: () => Element | null; next?: () => StepId | null; info?: boolean }
+> = {
+  add: {
+    // The sidebar's +; folded to a rail, its tree icon (which unfolds it).
+    target: () =>
+      shown('[data-testid="workspace-tree-add"]') || shown('[data-testid="sidebar-tree-rail"]'),
+    next: () => (modalOpen() ? "folder" : null),
+  },
+  folder: {
+    // The folder browser while it is open: it sits over the field.
+    target: () => $('[data-tour="folder-browse"]') || $('[data-tour="add-lane-folder"]'),
+    next: () => (modalOpen() ? null : composer() ? "prompt" : "add"),
+    info: true,
+  },
+  create: {
+    target: () => $('[data-tour="add-lane-create"]'),
+    next: () => (modalOpen() ? null : composer() ? "prompt" : "add"),
+  },
+  prompt: {
+    target: composer,
+    next: () => (sessionLive() ? "session" : null),
+  },
+  session: { target: () => shown('[data-testid="pane-grid"]'), info: true },
+  finish: { target: () => null, info: true },
+};
+
+function read(): StepId | null {
+  try {
+    const v = localStorage.getItem(KEY);
+    return (ORDER as string[]).includes(v ?? "") ? (v as StepId) : null;
+  } catch {
+    return null;
+  }
+}
+function write(v: StepId | "done") {
+  try {
+    localStorage.setItem(KEY, v);
+  } catch {
+    /* storage blocked: the tour just ends with the page */
+  }
+  window.dispatchEvent(new Event(EVENT));
+}
+
+/** Begin the tour at its first step (the setup's last button). */
+export const startTour = () => write("add");
+
+/** Mounted once in the layout; renders nothing unless a tour is running. */
+export function OnboardingTour() {
+  const { t } = useTranslation("onboarding");
+  const navigate = useNavigate();
+  const location = useLocation();
+  const [step, setStep] = useState<StepId | null>(read);
+  const [rect, setRect] = useState<DOMRect | null>(null);
+  // The dialog the target sits in, if any: the card goes beside the dialog.
+  const [box, setBox] = useState<DOMRect | null>(null);
+
+  useEffect(() => {
+    const sync = () => setStep(read());
+    window.addEventListener(EVENT, sync);
+    window.addEventListener("storage", sync);
+    return () => {
+      window.removeEventListener(EVENT, sync);
+      window.removeEventListener("storage", sync);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!step) return;
+    const tick = () => {
+      const def = STEPS[step];
+      const moved = def.next?.();
+      if (moved && moved !== step) return write(moved);
+      const el = def.target();
+      let r = el ? el.getBoundingClientRect() : null;
+      // The folder field's suggestions hang below it: light them too.
+      const list = el?.querySelector("[data-cwd-suggestions]")?.getBoundingClientRect();
+      if (r && list) {
+        const top = Math.min(r.top, list.top);
+        const left = Math.min(r.left, list.left);
+        r = new DOMRect(
+          left,
+          top,
+          Math.max(r.right, list.right) - left,
+          Math.max(r.bottom, list.bottom) - top
+        );
+      }
+      const d = el?.closest("[role=dialog]")?.getBoundingClientRect() ?? null;
+      setBox((prev) => (prev && d && prev.right === d.right ? prev : d));
+      // Only when it moved: a new DOMRect every tick would re-render forever.
+      setRect((prev) =>
+        prev &&
+        r &&
+        prev.x === r.x &&
+        prev.y === r.y &&
+        prev.width === r.width &&
+        prev.height === r.height
+          ? prev
+          : r
+      );
+    };
+    tick();
+    const id = window.setInterval(tick, POLL_MS);
+    return () => window.clearInterval(id);
+  }, [step, location]);
+
+  if (!step) return null;
+  const n = ORDER.indexOf(step) + 1;
+  const end = () => write("done");
+  const advance = () => {
+    if (step === "folder") return write("create");
+    if (step === "session") return write("finish");
+    end();
+  };
+  const lost = !rect && step !== "finish";
+
+  // Beside a narrow target (a field in a dialog: below it, the card would
+  // cover the rest of the dialog), else under it when there is room, else
+  // above; centred when there is no target (the finish, or the page moved).
+  const W = 320;
+  let style: React.CSSProperties = { left: "50%", top: "50%", transform: "translate(-50%, -50%)" };
+  if (rect) {
+    const right = (box ?? rect).right;
+    const top = Math.min(Math.max(12, rect.top), window.innerHeight - 220);
+    const left = Math.min(Math.max(12, rect.left), window.innerWidth - W - 12);
+    if (rect.width < window.innerWidth / 2 && right + W + 24 < window.innerWidth) {
+      style = { left: right + 16, top };
+    } else if (rect.bottom + 180 < window.innerHeight) {
+      style = { left, top: rect.bottom + 12 };
+    } else {
+      style = { left, top: Math.max(12, rect.top - 12), transform: "translateY(-100%)" };
+    }
+  }
+
+  return createPortal(
+    <div className="pointer-events-none fixed inset-0 z-[70]" data-testid="onboarding-tour">
+      {rect ? (
+        <div
+          aria-hidden
+          className="absolute rounded-lg ring-2 ring-accent transition-all duration-200"
+          style={{
+            left: rect.left - 6,
+            top: rect.top - 6,
+            width: rect.width + 12,
+            height: rect.height + 12,
+            boxShadow: "0 0 0 9999px rgba(0, 0, 0, 0.55)",
+          }}
+        />
+      ) : (
+        step === "finish" && <div aria-hidden className="absolute inset-0 bg-black/55" />
+      )}
+      <div
+        role="dialog"
+        aria-live="polite"
+        aria-label={t(`tour.${step}.title`)}
+        className="pointer-events-auto absolute w-80 space-y-2 rounded-xl border border-border bg-surface-1 p-4 shadow-2xl shadow-black/50"
+        style={style}
+      >
+        <p className="text-[11px] font-semibold uppercase tracking-[0.14em] text-fg-muted">
+          {t("tour.progress", { n, total: ORDER.length })}
+        </p>
+        <p className="text-sm font-semibold text-fg-primary">{t(`tour.${step}.title`)}</p>
+        <p className="text-xs leading-relaxed text-fg-secondary">{t(`tour.${step}.body`)}</p>
+        <div className="flex items-center gap-2 pt-1">
+          {step !== "finish" && (
+            <button type="button" onClick={end} className="btn-ghost px-0 text-xs">
+              {t("tour.skip")}
+            </button>
+          )}
+          <span className="flex-1" />
+          {lost && !location.pathname.startsWith("/workspace") && (
+            <button
+              type="button"
+              onClick={() => navigate("/workspace")}
+              className="btn-ghost border border-border text-xs"
+            >
+              {t("tour.goWorkspaces")}
+            </button>
+          )}
+          {STEPS[step].info && (
+            <button
+              type="button"
+              onClick={advance}
+              data-testid="onboarding-tour-next"
+              className="btn-primary text-xs"
+            >
+              {step === "finish" ? t("tour.done") : t("tour.next")}
+            </button>
+          )}
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}

client/src/components/onboarding/OnboardingWizard.tsx

@@ -0,0 +1,543 @@
+/**
+ * @file OnboardingWizard.tsx
+ * @description The first-run setup, once per ACCOUNT (docs/plans/onboarding;
+ * modelled on Orca's welcome): 1 the default agent — the AI tools detected on
+ * this machine, the rest behind "show more" — and the permission mode a new
+ * session starts in (never bypass: that stays per session); 2 the look —
+ * System / Dark / Light, a theme for each mode, language and terminal font;
+ * 3 the corner pet (`PetSettings`); 4 notifications — permission, sound,
+ * a test. Every choice is the same localStorage write Settings makes, so it
+ * applies at once and is synced to the account (`lib/userPrefs.ts`). Shown
+ * when the account has not been through it and has no workspace yet (one that
+ * has is marked done silently), or when Settings asks for it again. The last
+ * step hands over to the tour (`OnboardingTour`).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { useNavigate } from "react-router-dom";
+import { Check, ChevronLeft, Monitor, Moon, Play, Sun, Zap } from "lucide-react";
+import { api } from "../../lib/api";
+import { useDialog } from "../../hooks/useDialog";
+import { useAiTools } from "../../hooks/useAiTools";
+import { THEMES, useTheme, type Theme, type ThemeMode } from "../../hooks/useTheme";
+import { AiToolIcon } from "../AiToolIcon";
+import { Switch } from "../Switch";
+import { SettingsSegmented } from "../settings/SettingsRow";
+import { PetSettings } from "../settings/PetSettings";
+import { Swatch, THEME_LABELS } from "../settings/AppearanceSettings";
+import { markOnboarded, useOnboarding } from "../../lib/userPrefs";
+import {
+  DEFAULT_MODES,
+  readDefaultMode,
+  readDefaultTool,
+  writeDefaultMode,
+  writeDefaultTool,
+  type DefaultMode,
+} from "../../lib/sessionDefaults";
+import {
+  TERMINAL_FONTS,
+  readTerminalFont,
+  writeTerminalFont,
+  type TerminalFont,
+} from "../../lib/terminalFont";
+import {
+  NOTIF_SOUNDS,
+  loadNotifPrefs,
+  saveNotifPrefs,
+  type NotifPrefs,
+  type NotifSound,
+} from "../../lib/notifPrefs";
+import { notify, playSound } from "../../lib/notify";
+import { subscribeToPush } from "../../lib/push";
+import { startTour } from "./OnboardingTour";
+
+const STEPS = ["agent", "look", "pet", "notify"] as const;
+type Step = (typeof STEPS)[number];
+
+/** Mounted once in the layout: decides whether this account sees the setup. */
+export function OnboardingWizard() {
+  const { loaded, onboardedAt, forced } = useOnboarding();
+  const [show, setShow] = useState(false);
+  useEffect(() => {
+    if (!loaded || onboardedAt) return setShow(false);
+    if (forced) return setShow(true);
+    let alive = true;
+    api.lanes
+      .list()
+      .then((r) => {
+        if (!alive) return;
+        // An account already at work never needed a welcome.
+        if (r.lanes.length) void markOnboarded();
+        else setShow(true);
+      })
+      .catch(() => {
+        /* cannot tell: ask again next load rather than interrupt */
+      });
+    return () => {
+      alive = false;
+    };
+  }, [loaded, onboardedAt, forced]);
+  return show ? <Wizard /> : null;
+}
+
+function Wizard() {
+  const { t } = useTranslation("onboarding");
+  const navigate = useNavigate();
+  const [index, setIndex] = useState(0);
+  const step: Step = STEPS[index] ?? "agent";
+  const last = index === STEPS.length - 1;
+  const panelRef = useRef<HTMLDivElement>(null);
+  useDialog(true, panelRef);
+
+  const skip = () => void markOnboarded();
+  const next = () => {
+    if (!last) return setIndex(index + 1);
+    void markOnboarded();
+    startTour();
+    navigate("/");
+  };
+
+  // Ctrl/⌘+Enter continues, like Orca.
+  const nextRef = useRef(next);
+  nextRef.current = next;
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Enter" && (e.ctrlKey || e.metaKey)) {
+        e.preventDefault();
+        nextRef.current();
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  return (
+    <div className="fixed inset-0 z-[65] flex items-center justify-center bg-black/70 p-4 backdrop-blur-sm">
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="onboarding-title"
+        data-testid="onboarding-wizard"
+        className="flex h-[min(820px,92vh)] w-full max-w-4xl flex-col rounded-2xl border border-border bg-surface-1 shadow-2xl shadow-black/50"
+      >
+        <div className="space-y-5 px-8 pt-7">
+          <div className="flex items-center gap-2.5">
+            <img src="/favicon.svg" alt="" className="h-7 w-7" />
+            <span className="text-sm font-semibold text-fg-primary">{t("brand")}</span>
+          </div>
+          <div className="flex items-center gap-3" aria-hidden>
+            {STEPS.map((s, i) => (
+              <span
+                key={s}
+                className={`h-1 w-9 rounded-full ${i <= index ? "bg-fg-primary" : "bg-surface-4"}`}
+              />
+            ))}
+            <span className="text-xs text-fg-muted">
+              {t("progress", { n: index + 1, total: STEPS.length })}
+            </span>
+          </div>
+        </div>
+
+        <div className="min-h-0 flex-1 overflow-y-auto px-8 py-6">
+          {step === "agent" && <AgentStep />}
+          {step === "look" && <LookStep />}
+          {step === "pet" && (
+            <StepHead title={t("pet.title")} body={t("pet.body")}>
+              <PetSettings />
+            </StepHead>
+          )}
+          {step === "notify" && <NotifyStep />}
+        </div>
+
+        <div className="flex items-center gap-2 border-t border-border px-8 py-4">
+          <button type="button" onClick={skip} className="btn-ghost text-xs">
+            {t("skip")}
+          </button>
+          <span className="flex-1" />
+          {index > 0 && (
+            <button
+              type="button"
+              onClick={() => setIndex(index - 1)}
+              className="btn-ghost border border-border text-xs"
+            >
+              <ChevronLeft className="h-3.5 w-3.5" />
+              {t("back")}
+            </button>
+          )}
+          <button
+            type="button"
+            onClick={next}
+            data-testid="onboarding-next"
+            className="btn-primary text-xs"
+          >
+            {last ? t("finish") : t("continue")}
+            <kbd className="ml-1 rounded border border-white/30 px-1 text-[10px] font-normal opacity-80">
+              Ctrl ↵
+            </kbd>
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function StepHead({
+  eyebrow,
+  title,
+  body,
+  children,
+}: {
+  eyebrow?: string;
+  title: string;
+  body: string;
+  children: ReactNode;
+}) {
+  return (
+    <section className="space-y-6">
+      <div className="space-y-2">
+        {eyebrow && (
+          <p className="text-[11px] font-semibold uppercase tracking-[0.18em] text-fg-muted">
+            {eyebrow}
+          </p>
+        )}
+        <h2 id="onboarding-title" className="text-3xl font-bold text-fg-primary">
+          {title}
+        </h2>
+        <p className="text-sm text-fg-secondary">{body}</p>
+      </div>
+      {children}
+    </section>
+  );
+}
+
+function AgentStep() {
+  const { t } = useTranslation("onboarding");
+  const aiTools = useAiTools();
+  const installed = aiTools.tools.filter((x) => x.installed && x.enabled);
+  const others = aiTools.tools.filter((x) => !(x.installed && x.enabled));
+  const [more, setMore] = useState(false);
+  const [picked, setPicked] = useState<string | null>(readDefaultTool);
+  const current =
+    (picked && installed.some((x) => x.id === picked) ? picked : null) ??
+    aiTools.defaultId ??
+    installed[0]?.id ??
+    null;
+  const [mode, setMode] = useState<DefaultMode>(() => readDefaultMode() as DefaultMode);
+
+  const pick = (id: string) => {
+    writeDefaultTool(id);
+    setPicked(id);
+  };
+
+  return (
+    <StepHead eyebrow={t("agent.eyebrow")} title={t("agent.title")} body={t("agent.body")}>
+      <div className="space-y-3">
+        <p className="flex items-center gap-2 text-[11px] font-semibold uppercase tracking-[0.14em] text-fg-muted">
+          <span className="h-1.5 w-1.5 rounded-full bg-status-success" />
+          {t("agent.detected", { count: installed.length })}
+        </p>
+        {aiTools.loaded && !installed.length && (
+          <p className="text-sm text-fg-muted">{t("agent.none")}</p>
+        )}
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
+          {installed.map((tool) => {
+            const selected = tool.id === current;
+            return (
+              <button
+                key={tool.id}
+                type="button"
+                onClick={() => pick(tool.id)}
+                aria-pressed={selected}
+                data-testid={`onboarding-agent-${tool.id}`}
+                className={`relative flex items-center gap-3 rounded-xl border px-4 py-3.5 text-left transition-colors ${
+                  selected
+                    ? "border-accent bg-accent/10 ring-1 ring-accent/50"
+                    : "border-border bg-surface-2 hover:border-border-light"
+                }`}
+              >
+                <AiToolIcon tool={tool} className="h-6 w-6 shrink-0" />
+                <span className="min-w-0">
+                  <span className="block truncate text-sm font-medium text-fg-primary">
+                    {tool.label}
+                  </span>
+                  <span className="block truncate font-mono text-xs text-fg-muted">
+                    {tool.command || tool.id}
+                  </span>
+                </span>
+                {selected && (
+                  <span className="absolute right-2.5 top-2.5 flex h-5 w-5 items-center justify-center rounded-full bg-accent-solid text-white">
+                    <Check className="h-3 w-3" />
+                  </span>
+                )}
+              </button>
+            );
+          })}
+          {more &&
+            others.map((tool) => (
+              <div
+                key={tool.id}
+                className="flex items-center gap-3 rounded-xl border border-dashed border-border px-4 py-3.5 opacity-60"
+              >
+                <AiToolIcon tool={tool} className="h-6 w-6 shrink-0" />
+                <span className="min-w-0">
+                  <span className="block truncate text-sm text-fg-primary">{tool.label}</span>
+                  <span className="block text-xs text-fg-muted">{t("agent.notInstalled")}</span>
+                </span>
+              </div>
+            ))}
+        </div>
+        {others.length > 0 && (
+          <button
+            type="button"
+            onClick={() => setMore(!more)}
+            className="text-xs font-medium text-fg-secondary hover:text-fg-primary"
+          >
+            {more ? t("agent.less") : `${t("agent.more", { count: others.length })} →`}
+          </button>
+        )}
+      </div>
+
+      <div className="space-y-2 rounded-xl border border-border bg-surface-2 px-4 py-3.5">
+        <div className="flex flex-wrap items-center gap-3">
+          <span className="text-sm font-medium text-fg-primary">{t("agent.permission")}</span>
+          <SettingsSegmented
+            ariaLabel={t("agent.permission")}
+            value={mode}
+            onChange={(m) => {
+              writeDefaultMode(m);
+              setMode(m);
+            }}
+            options={DEFAULT_MODES.map((m) => ({ value: m, label: t(`agent.modes.${m}`) }))}
+          />
+        </div>
+        <p className="text-xs text-fg-muted">{t("agent.permissionHint")}</p>
+      </div>
+    </StepHead>
+  );
+}
+
+const MODE_CARDS: { mode: ThemeMode; Icon: typeof Moon }[] = [
+  { mode: "system", Icon: Monitor },
+  { mode: "dark", Icon: Moon },
+  { mode: "light", Icon: Sun },
+];
+
+function LookStep() {
+  const { t, i18n } = useTranslation("onboarding");
+  const { t: ts } = useTranslation("settings");
+  const { mode, themeFor, setMode, setThemeFor } = useTheme();
+  const [font, setFont] = useState<TerminalFont>(readTerminalFont);
+
+  return (
+    <StepHead title={t("look.title")} body={t("look.body")}>
+      <div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
+        {MODE_CARDS.map(({ mode: m, Icon }) => {
+          const selected = mode === m;
+          return (
+            <button
+              key={m}
+              type="button"
+              onClick={() => setMode(m)}
+              aria-pressed={selected}
+              data-testid={`onboarding-mode-${m}`}
+              className={`rounded-xl border p-2.5 text-left transition-colors ${
+                selected
+                  ? "border-accent ring-2 ring-accent/40"
+                  : "border-border hover:border-border-light"
+              }`}
+            >
+              {m === "system" ? (
+                <div className="grid grid-cols-2 overflow-hidden rounded-md">
+                  <Swatch mode="dark" name={themeFor.dark} />
+                  <Swatch mode="light" name={themeFor.light} />
+                </div>
+              ) : (
+                <Swatch mode={m} name={themeFor[m]} />
+              )}
+              <span className="flex items-center gap-1.5 px-1 pt-2 text-sm font-medium text-fg-primary">
+                <Icon className="h-3.5 w-3.5" />
+                {t(`look.modes.${m}`)}
+                <span className="ml-auto text-[11px] font-normal text-fg-muted">
+                  {t(`look.modeHints.${m}`)}
+                </span>
+              </span>
+            </button>
+          );
+        })}
+      </div>
+
+      {(["dark", "light"] as Theme[]).map((group) => (
+        <div key={group} className="space-y-2">
+          <p className="text-xs font-medium text-fg-secondary">
+            {t(group === "dark" ? "look.darkThemes" : "look.lightThemes")}
+          </p>
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+            {THEMES[group].map((name) => {
+              const selected = themeFor[group] === name;
+              const label = THEME_LABELS[name] ?? ts("appearance.default");
+              return (
+                <button
+                  key={name}
+                  type="button"
+                  onClick={() => setThemeFor(group, name)}
+                  aria-pressed={selected}
+                  aria-label={`${t(group === "dark" ? "look.darkThemes" : "look.lightThemes")}: ${label}`}
+                  className={`rounded-lg border p-1 text-left transition-colors ${
+                    selected
+                      ? "border-accent ring-2 ring-accent/40"
+                      : "border-border hover:border-border-light"
+                  }`}
+                >
+                  <Swatch mode={group} name={name} />
+                  <span className="block px-1 pt-1 text-[11px] text-fg-primary">{label}</span>
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+        <div className="space-y-2">
+          <p className="text-xs font-medium text-fg-secondary">{t("look.language")}</p>
+          <SettingsSegmented
+            ariaLabel={t("look.language")}
+            value={(i18n.resolvedLanguage ?? i18n.language).startsWith("vi") ? "vi" : "en"}
+            onChange={(v) => void i18n.changeLanguage(v)}
+            options={[
+              { value: "en" as const, label: ts("language.names.en") },
+              { value: "vi" as const, label: ts("language.names.vi") },
+            ]}
+          />
+        </div>
+        <div className="space-y-2">
+          <p className="text-xs font-medium text-fg-secondary">{t("look.font")}</p>
+          <SettingsSegmented
+            ariaLabel={t("look.font")}
+            value={font}
+            onChange={(f) => {
+              writeTerminalFont(f);
+              setFont(f);
+            }}
+            options={(Object.keys(TERMINAL_FONTS) as TerminalFont[]).map((f) => ({
+              value: f,
+              label: (
+                <span style={{ fontFamily: TERMINAL_FONTS[f] }}>
+                  {ts(`terminalFont.names.${f}`)}
+                </span>
+              ),
+            }))}
+          />
+        </div>
+      </div>
+      <p className="text-xs text-fg-muted">{t("look.more")}</p>
+    </StepHead>
+  );
+}
+
+function NotifyStep() {
+  const { t } = useTranslation("onboarding");
+  const { t: ts } = useTranslation("settings");
+  const [prefs, setPrefs] = useState<NotifPrefs>(loadNotifPrefs);
+  const [result, setResult] = useState<string | null>(null);
+  const supported = typeof window !== "undefined" && "Notification" in window;
+  const [permission, setPermission] = useState(() =>
+    supported ? Notification.permission : "default"
+  );
+  const update = (patch: Partial<NotifPrefs>) => {
+    const next = { ...prefs, ...patch };
+    saveNotifPrefs(next);
+    setPrefs(next);
+  };
+
+  const enable = async (on: boolean) => {
+    if (!on) return update({ enabled: false });
+    if (supported && Notification.permission !== "granted") {
+      const perm = await Notification.requestPermission();
+      setPermission(perm);
+      if (perm !== "granted") return;
+    }
+    update({ enabled: true });
+    await subscribeToPush().catch(() => {
+      /* the local fallback still shows them */
+    });
+  };
+
+  const test = async () => {
+    const r = await notify(ts("notifications.testTitle"), ts("notifications.testBody"));
+    setResult(
+      r.via === "push" || r.via === "native"
+        ? ts("notifications.testSent")
+        : r.via === "local"
+          ? ts("notifications.testLocal")
+          : r.via === "blocked"
+            ? ts("notifications.testBlocked")
+            : ts("notifications.testFailed")
+    );
+  };
+
+  return (
+    <StepHead title={t("notify.title")} body={t("notify.body")}>
+      <div className="space-y-4 rounded-xl border border-border bg-surface-2 px-4 py-4">
+        <div className="flex items-center gap-3">
+          <div className="min-w-0 flex-1">
+            <p className="text-sm font-medium text-fg-primary">{t("notify.enable")}</p>
+            <p className="text-xs text-fg-muted">{t("notify.enableHint")}</p>
+          </div>
+          <Switch
+            checked={prefs.enabled}
+            onChange={(v) => void enable(v)}
+            label={t("notify.enable")}
+          />
+        </div>
+        {permission === "denied" && (
+          <p className="text-xs text-status-danger">{t("notify.blocked")}</p>
+        )}
+        <div className="flex flex-wrap items-center gap-2 border-t border-border pt-4">
+          <span className="mr-2 text-sm text-fg-primary">{t("notify.sound")}</span>
+          <select
+            aria-label={t("notify.sound")}
+            value={prefs.sound}
+            onChange={(e) => {
+              const sound = e.target.value as NotifSound;
+              update({ sound });
+              playSound(sound);
+            }}
+            className="select py-1 text-xs"
+          >
+            {NOTIF_SOUNDS.map((k) => (
+              <option key={k} value={k}>
+                {ts(`notifications.sound.${k}`)}
+              </option>
+            ))}
+          </select>
+          <button
+            type="button"
+            onClick={() => playSound(prefs.sound)}
+            disabled={prefs.sound === "none"}
+            className="btn-ghost text-xs disabled:opacity-50"
+          >
+            <Play className="h-3 w-3" />
+            {t("notify.preview")}
+          </button>
+          <button
+            type="button"
+            onClick={() => void test()}
+            className="btn-ghost border border-border text-xs"
+          >
+            <Zap className="h-3 w-3" />
+            {t("notify.test")}
+          </button>
+        </div>
+        {result && (
+          <p role="status" className="text-xs text-fg-secondary">
+            {result}
+          </p>
+        )}
+      </div>
+    </StepHead>
+  );
+}

client/src/components/onboarding/__tests__/Onboarding.test.tsx

@@ -0,0 +1,256 @@
+/**
+ * @file Onboarding.test.tsx
+ * @description The first-run setup (docs/plans/onboarding): the account's
+ * preferences are loaded into localStorage on sign-in and every later change
+ * is sent back; the starting choices never hold bypass; the wizard shows only
+ * for an account that is new to it, writes each pick like Settings does and
+ * ends in the tour; the tour follows the real UI step by step.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { act, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { MemoryRouter } from "react-router-dom";
+
+const prefsMock = vi.fn();
+const saveMock = vi.fn();
+const onboardedMock = vi.fn();
+const lanesMock = vi.fn();
+
+vi.mock("../../../lib/api", async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return {
+    ...actual,
+    api: {
+      me: {
+        prefs: () => prefsMock(),
+        savePrefs: (p: unknown) => saveMock(p),
+        onboarded: () => onboardedMock(),
+      },
+      lanes: { list: () => lanesMock() },
+      aiTools: {
+        iconUrl: (id: string) => `/api/ai-tools/${id}/icon`,
+        list: async () => ({
+          default: "claude",
+          catalog: [],
+          tools: [
+            {
+              id: "claude",
+              label: "Claude Code",
+              command: "claude",
+              installed: true,
+              enabled: true,
+            },
+            { id: "codex", label: "Codex", command: "codex", installed: true, enabled: true },
+            { id: "kimi", label: "Kimi Code", command: "kimi", installed: false, enabled: true },
+          ],
+        }),
+      },
+    },
+  };
+});
+vi.mock("../../settings/PetSettings", () => ({
+  PetSettings: () => <div data-testid="pet-settings" />,
+}));
+
+import { __resetUserPrefs, hydrate, useOnboarding } from "../../../lib/userPrefs";
+import { readDefaultMode, writeDefaultMode } from "../../../lib/sessionDefaults";
+import { OnboardingWizard } from "../OnboardingWizard";
+import { OnboardingTour, startTour } from "../OnboardingTour";
+import { __resetAiTools } from "../../../hooks/useAiTools";
+
+beforeEach(() => {
+  localStorage.clear();
+  __resetUserPrefs();
+  __resetAiTools();
+  prefsMock.mockReset();
+  saveMock.mockReset().mockResolvedValue({ prefs: {}, onboardedAt: null });
+  onboardedMock.mockReset().mockResolvedValue({ prefs: {}, onboardedAt: "2026-10-08T00:00:00Z" });
+  lanesMock.mockReset().mockResolvedValue({ lanes: [], counts: {} });
+});
+
+describe("account preferences", () => {
+  it("loads the account's values, sends up this browser's, then every change", async () => {
+    vi.useFakeTimers();
+    try {
+      localStorage.setItem("agenthub.terminal.font", "maple");
+      localStorage.setItem("theme", "dark");
+      prefsMock.mockResolvedValue({ prefs: { theme: "light" }, onboardedAt: null });
+      await hydrate();
+      expect(localStorage.getItem("theme")).toBe("light");
+      await vi.advanceTimersByTimeAsync(10);
+      expect(saveMock).toHaveBeenCalledWith(
+        expect.objectContaining({ "agenthub.terminal.font": "maple" })
+      );
+      saveMock.mockClear();
+      localStorage.setItem("agenthub.theme.dark", "darcula");
+      localStorage.setItem("unrelated.key", "x");
+      localStorage.removeItem("agenthub.pet");
+      await vi.advanceTimersByTimeAsync(500);
+      expect(saveMock).toHaveBeenCalledTimes(1);
+      expect(saveMock).toHaveBeenCalledWith({
+        "agenthub.theme.dark": "darcula",
+        "agenthub.pet": null,
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("never keeps bypass as the starting permission mode", () => {
+    localStorage.setItem("agenthub.permissionMode", "bypassPermissions");
+    expect(readDefaultMode()).toBe("auto");
+    writeDefaultMode("bypassPermissions" as never);
+    expect(localStorage.getItem("agenthub.permissionMode")).toBe("bypassPermissions");
+    writeDefaultMode("plan");
+    expect(readDefaultMode()).toBe("plan");
+  });
+});
+
+function Probe() {
+  const s = useOnboarding();
+  return <span data-testid="onboarded">{s.onboardedAt ?? "no"}</span>;
+}
+const renderWizard = () =>
+  render(
+    <MemoryRouter>
+      <OnboardingWizard />
+      <Probe />
+    </MemoryRouter>
+  );
+
+describe("the setup wizard", () => {
+  it("does not show before the account's preferences load, nor once done", async () => {
+    renderWizard();
+    expect(screen.queryByTestId("onboarding-wizard")).toBeNull();
+    prefsMock.mockResolvedValue({ prefs: {}, onboardedAt: "2026-01-01T00:00:00Z" });
+    await act(() => hydrate());
+    expect(screen.queryByTestId("onboarding-wizard")).toBeNull();
+  });
+
+  it("skips itself for an account that already has a workspace", async () => {
+    lanesMock.mockResolvedValue({ lanes: [{ id: 1 }], counts: {} });
+    prefsMock.mockResolvedValue({ prefs: {}, onboardedAt: null });
+    renderWizard();
+    await act(() => hydrate());
+    await waitFor(() => expect(onboardedMock).toHaveBeenCalled());
+    expect(screen.queryByTestId("onboarding-wizard")).toBeNull();
+  });
+
+  it("walks four steps, saving each pick, and ends in the tour", async () => {
+    const user = userEvent.setup();
+    prefsMock.mockResolvedValue({ prefs: {}, onboardedAt: null });
+    renderWizard();
+    await act(() => hydrate());
+    await screen.findByTestId("onboarding-wizard");
+    expect(screen.getByText("Pick your default agent")).toBeInTheDocument();
+    await user.click(await screen.findByTestId("onboarding-agent-codex"));
+    expect(localStorage.getItem("agenthub.defaultTool")).toBe("codex");
+    // A tool that is not installed is not offered until asked for, and never pickable.
+    expect(screen.queryByText("Kimi Code")).toBeNull();
+    await user.click(screen.getByText(/Show 1 more agents/));
+    expect(screen.getByText("Kimi Code").closest("button")).toBeNull();
+    await user.click(screen.getByRole("radio", { name: "Plan" }));
+    expect(localStorage.getItem("agenthub.permissionMode")).toBe("plan");
+
+    await user.click(screen.getByTestId("onboarding-next"));
+    expect(screen.getByText("Make it feel like home")).toBeInTheDocument();
+    await user.click(screen.getByTestId("onboarding-mode-light"));
+    expect(localStorage.getItem("theme")).toBe("light");
+    await user.click(screen.getByRole("button", { name: "Light theme: Canvas" }));
+    expect(localStorage.getItem("agenthub.theme.light")).toBe("canvas");
+
+    await user.click(screen.getByTestId("onboarding-next"));
+    expect(screen.getByTestId("pet-settings")).toBeInTheDocument();
+    await user.click(screen.getByTestId("onboarding-next"));
+    expect(screen.getByText("Set up notifications")).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: /Add your first workspace/ }));
+    await waitFor(() => expect(onboardedMock).toHaveBeenCalled());
+    expect(screen.queryByTestId("onboarding-wizard")).toBeNull();
+    expect(localStorage.getItem("agenthub.tour")).toBe("add");
+  });
+
+  it("is skipped for good with Skip setup", async () => {
+    const user = userEvent.setup();
+    prefsMock.mockResolvedValue({ prefs: {}, onboardedAt: null });
+    renderWizard();
+    await act(() => hydrate());
+    await user.click(await screen.findByRole("button", { name: "Skip setup" }));
+    await waitFor(() => expect(screen.getByTestId("onboarded").textContent).not.toBe("no"));
+    expect(onboardedMock).toHaveBeenCalled();
+    expect(localStorage.getItem("agenthub.tour")).toBeNull();
+  });
+});
+
+describe("the tour", () => {
+  const mount = (html: string) => {
+    const host = document.createElement("div");
+    host.innerHTML = html;
+    document.body.appendChild(host);
+    return host;
+  };
+  // jsdom has no layout: give the targets a box.
+  const boxed = () =>
+    vi.spyOn(Element.prototype, "getBoundingClientRect").mockReturnValue({
+      x: 10,
+      y: 10,
+      left: 10,
+      top: 10,
+      width: 100,
+      height: 30,
+      right: 110,
+      bottom: 40,
+      toJSON: () => ({}),
+    } as DOMRect);
+
+  it("follows the real UI: add → folder → create → prompt", async () => {
+    const spy = boxed();
+    const user = userEvent.setup();
+    const page = mount('<button data-testid="workspace-tree-add">+</button>');
+    try {
+      startTour();
+      render(
+        <MemoryRouter initialEntries={["/workspace"]}>
+          <OnboardingTour />
+        </MemoryRouter>
+      );
+      expect(await screen.findByText("Create your first workspace")).toBeInTheDocument();
+      // The dialog opened: the tour moves on by itself.
+      const dialog = mount(
+        '<div data-tour="add-lane"><div data-tour="add-lane-folder"></div><button data-tour="add-lane-create"></button></div>'
+      );
+      expect(await screen.findByText("Choose the project folder")).toBeInTheDocument();
+      await user.click(screen.getByTestId("onboarding-tour-next"));
+      expect(screen.getByText("Create it")).toBeInTheDocument();
+      // Created: the dialog is gone and the workspace's prompt box is there.
+      dialog.remove();
+      page.innerHTML = '<div data-testid="workspace-home-composer"></div>';
+      expect(await screen.findByText("Start your first session")).toBeInTheDocument();
+      expect(localStorage.getItem("agenthub.tour")).toBe("prompt");
+      await user.click(screen.getByRole("button", { name: "Skip tour" }));
+      expect(screen.queryByTestId("onboarding-tour")).toBeNull();
+      expect(localStorage.getItem("agenthub.tour")).toBe("done");
+    } finally {
+      spy.mockRestore();
+      page.remove();
+    }
+  });
+
+  it("goes back to Add workspace when the dialog closes with nothing made", async () => {
+    const spy = boxed();
+    const page = mount('<button data-testid="workspace-tree-add">+</button>');
+    try {
+      localStorage.setItem("agenthub.tour", "create");
+      render(
+        <MemoryRouter initialEntries={["/workspace"]}>
+          <OnboardingTour />
+        </MemoryRouter>
+      );
+      expect(await screen.findByText("Create your first workspace")).toBeInTheDocument();
+    } finally {
+      spy.mockRestore();
+      page.remove();
+    }
+  });
+});