fix: v2.8.10 — the server starts again on plugin installs (js-yaml is a runtime dependency)

v2.8.9 crashed at start on every plugin install with "Cannot find module
'js-yaml'": server/lib/lane-detect.js requires it, but it was only a
devDependency that redoc used to pull in, and v2.8.8 dropped redoc. The
plugin installs with --omit=dev. This box hid it: Debian's global
/usr/share/nodejs has js-yaml. Reproduced with a pruned install and the
global paths off; fixed by moving js-yaml (and argparse in the lock) to
dependencies. New runtime-deps.test.js fails on any server/ require that is
not a dependency.

.claude-plugin/plugin.json

@@ -22,7 +22,8 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-handler.js\" PreToolUse",
-            "timeout": 5
+            "timeout": 5,
+            "async": true
           }
         ]
       }
@@ -34,7 +35,8 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-handler.js\" PostToolUse",
-            "timeout": 5
+            "timeout": 5,
+            "async": true
           }
         ]
       }

.env.example

@@ -72,9 +72,21 @@
 #   DASHBOARD_SESSION_SYNC_MS=30000
 
 # Hourly database upkeep: a non-blocking WAL checkpoint (the WAL then shrinks
-# to 64 MB) and PRAGMA optimize. 0 turns it off. Never VACUUMs.
+# to 64 MB), PRAGMA optimize, the opt-in retention below and a bounded
+# incremental_vacuum. 0 turns it off. Never a full VACUUM (that is Settings →
+# Data → Compact, on a click).
 #   DASHBOARD_DB_MAINTAIN_MS=3600000
 
+# Automatic retention (OFF unless set): finished sessions that started more
+# than N days ago (1–3650) are purged by the hourly upkeep. Usually set from
+# Settings → Data → Session cleanup, which writes it to the settings file.
+#   AGENTHUB_RETENTION_DAYS=90
+
+# Update check interval (ms, default 3600000 = 1 h, minimum 60000). A tick
+# with no browser connected is skipped; the next browser to connect gets one.
+# DASHBOARD_UPDATE_CHECK=0 turns the scheduled check off.
+#   DASHBOARD_UPDATE_CHECK_INTERVAL_MS=3600000
+
 # Poll interval (ms) for Antigravity CLI sessions and tokens, read from agy's
 # own ~/.gemini/antigravity-cli/conversations/*.db (0 disables; default: 15000).
 #   DASHBOARD_ANTIGRAVITY_POLL_MS=15000

.prettierignore

@@ -11,3 +11,4 @@ client/package-lock.json
 *.md
 *.yml
 *.yaml
+server/vendor/

AGENTS.md

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

ARCHITECTURE.md

@@ -310,7 +310,7 @@ graph TD
 |---------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `server/index.js`         | Express app setup, middleware, route mounting, static file serving in production, HTTP server creation. Static middleware sets explicit `Cache-Control` headers — `immutable` for `/assets/*`, `no-cache, must-revalidate` for `index.html` / `sw.js` / `manifest.json`, a short revalidation window otherwise — so a rebuild always replaces the in-browser bundle without a hard refresh. Runs a periodic maintenance sweep — cadence derived from `DASHBOARD_STALE_MINUTES` (¼ of the threshold, clamped to 60 s – 5 min, default ~45 min) — that abandons stale sessions with transcript cache eviction and scans active sessions for new compaction entries by reading `sessions.transcript_path` directly (an O(active sessions) lookup; the previous `SELECT DISTINCT json_extract(events.data,'$.transcript_path')` scan grew with the events table and is gone). **Error detection watchdog** runs every 15 seconds: finds active sessions with no recent hook events (>10 s stale), re-reads their transcript files looking for API errors (401 auth, rate limits, quota exhaustion), derives transcript paths from session `cwd` for imported sessions, and marks sessions/agents as `error` when API errors are found — catches cases where the CLI doesn't fire a hook after API errors. The same watchdog also performs **user-interrupt (Esc) recovery**: `Esc` fires no hook, so a cancelled turn would otherwise leave the main agent stuck `working`. It detects this two ways — (a) the transcript's `[Request interrupted by user]` marker, surfaced as `result.pendingInterrupt` from `TranscriptCache` (computed from transcript ordering alone, immune to server/transcript clock skew), and (b) an idle-working fallback for an Esc pressed *before any output* (which writes no marker): when the main agent has been `working` with `current_tool` null and neither a hook event nor the transcript mtime has advanced for `DASHBOARD_WORKING_IDLE_SECONDS` (default 120) — and moves the session to **Waiting** (agent → `waiting`, `awaiting_input_since` stamped) with an `Interrupted` event. Triggers legacy session import (with active-session detection for recently-modified JSONL files) and compaction backfill on startup, plus a boot **liveness reap** — immediately for rows from a previous run and again ~5 s later for rows the startup sync just imported (see the `routes/hooks.js` row) — so sessions that died while the dashboard was down never render as Waiting. Also starts the **Remote Data Sources** sync poller (`startRemoteSourceSync`) that pulls each enabled remote source on an interval — `DASHBOARD_REMOTE_SYNC_MS` (default 60000; 0 disables) — reusing `server/lib/remote-sync.js`. **Graceful shutdown** (SIGTERM/SIGINT) tears down in order: drop realtime clients first (`closeWebSocket` terminates WS clients so their sockets release), then `httpServer.close()` to stop new connections, then `httpServer.closeAllConnections()` to drop lingering keep-alive sockets so `close()` fires promptly, and only **then** close SQLite — inside the `close()` callback, after the HTTP server has drained. Closing the DB before drain made in-flight requests throw `The database connection is not open`; leaving WS/keep-alive sockets open stalled the shutdown until the 5 s force-exit backstop (the "waiting for graceful termination" hang under `node --watch`). A second signal forces an immediate exit                                                                                                                                                                                                                    |
 | `server/openapi.js`       | OpenAPI 3.0.3 document generator for the backend API (metadata, schemas, endpoint paths), merging supplementary fragments from `server/openapi-extra/` in `createOpenApiSpec()`. Feeds the raw spec endpoint (`/api/openapi.json`), Swagger UI (`/api/docs`), **ReDoc** (`/api/redoc`, served via `server/lib/redoc.js` with a self-hosted bundle — never a CDN), and the committed `openapi.yaml` regenerated by `npm run openapi:yaml`                                                                                                                                                                                                                                                          |
-| `server/lib/redoc.js`     | Serves the **ReDoc** API reference (`/api/redoc`) as a self-hosted three-panel rendering of the OpenAPI spec, with the ReDoc bundle served locally from `/api/redoc/redoc.standalone.js` (bundled via the `redoc` dependency, never a CDN) so the reference works fully offline / air-gapped                                                                                                                                                                                                                                                                                                                                                                            |
+| `server/lib/redoc.js`     | Serves the **ReDoc** API reference (`/api/redoc`) as a self-hosted three-panel rendering of the OpenAPI spec, with the ReDoc bundle served locally from `/api/redoc/redoc.standalone.js` (vendored under `server/vendor/redoc/` — the `redoc` npm package is not a dependency — never a CDN) so the reference works fully offline / air-gapped                                                                                                                                                                                                                                                                                                                                                                            |
 | `server/openapi-extra/`   | Supplementary OpenAPI path/schema fragments merged into the spec by `createOpenApiSpec()` — covers `cc-config.js`, `push.js`, `run.js`, and `misc.js` route groups                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `server/db.js`            | SQLite connection with WAL mode, schema migration (CREATE TABLE IF NOT EXISTS + ALTER TABLE for column additions), all prepared statements as a reusable `stmts` object. Tries `better-sqlite3` first, falls back to `node:sqlite` via `compat-sqlite.js`. Migrations use literal defaults for ALTER TABLE since SQLite does not support expressions like `strftime()` in column defaults added via ALTER TABLE                                                                                                                      |
 | `server/compat-sqlite.js` | Compatibility wrapper that gives Node.js built-in `node:sqlite` (`DatabaseSync`) the same API as `better-sqlite3` — pragma, transaction, prepare. Used as automatic fallback when the native module is unavailable (Node 22+) Maps every better-sqlite3 API the server uses — `function` (the `trim_event_data` SQL function `db.js` registers at boot), `stmt.pluck()`, the `readonly`/`fileMustExist` open options — and `db.js` exports the chosen class as `Database` so other SQLite files (agy's conversations) open with the same driver. A plugin install has NO better-sqlite3 build, so this is production there; `server/__tests__/compat-sqlite.test.js` boots `db.js` with better-sqlite3 blocked because the rest of the suite never runs on it. |
@@ -374,8 +374,8 @@ graph TD
 | `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/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`. |
+| `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`, `/:id/git/download` and `/:id/git/branches` are read-only and unguarded like `/:id/git`, while `POST /:id/git/upload` (create-only, `lane-file-transfer.js`) and `POST /:id/git/:action` are 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 |
 | `lib/lane-profile.js`     | The stack seam. Resolves `<repo>/.agenthub/profile/` from the lane's own working copy first (a branch that edits its boot command must boot with it), the source repo second. `profile.env` is **parsed, not sourced** — `$(…)` stays literal, because sourcing repo shell into the dashboard process would be a code-execution path. `runHook` spawns `bash <hook>` with an argv array through a wrapper that `export -f`s `harness_spawn`/`die`, exports Shipyard's env contract verbatim (`LANE` is the **slot**, plus `<NAME>_PORT` per declared port, plus A2's `DB_NAME`/`DATABASE_URL`/`TEST_DATABASE_URL`/`PG_HOST`/`PG_PORT`/`PG_USER`/`REDIS_URL`/`REDIS_HOST`/`REDIS_PORT`/`UPLOAD_DIR` when their profile declaration is present) so its profiles port unchanged, scrubs `GIT_*` exactly as `worktree.js:git()` does, redacts any `secrets.js` password from its output before it reaches the log file or the `lane_hook_output` broadcast, and streams the rest to both `$LOG_DIR/<hook>.log` and that broadcast. Hook names come from a fixed allowlist, never from a request |
@@ -385,7 +385,8 @@ graph TD
 | `lib/lane-env.js`         | (A2) `seedEnv` copies a repo's real `.env` into a lane on first boot (or `--force`) and rewrites the declared `ENV_REWRITE` keys (`DATABASE_URL`/`REDIS_URL`/`UPLOAD_DIR`) in place, byte-identical otherwise. A `--force` refresh preserves `ENV_PRESERVE` keys (e.g. `JWT_SECRET`) from the lane's own existing file — swapping in the source's secret would 401 a running lane until reboot. Falls back to `.env.example` with a warning when the source is missing. Refuses on an adopted lane: that file is the user's real config |
 | `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-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; in a folder that is not a git repo they, and `listTreeAll`, read the disk instead through `walkFolder` — realpath-confined, symlinks never followed, `.git` hidden, `node_modules` never entered, 20 000 entries at most). 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/lane-file-transfer.js` | (#78) The Files tab's download and upload. `openDownload` streams one working file of any type (up to 512 MB) behind the file read's guards (`lanePath`, `resolveInLane` realpath confinement, `isSecretOnDisk`, `openSafe` for a member's file); the route serves it as an `application/octet-stream` attachment under a `sandbox` CSP with `nosniff`. `saveUpload` only CREATES (`EEXISTS` for a taken name, a symlink included), into an existing folder, never under `.git`, never a secret name, at most 25 MB — under S3 as the folder's member through `write-as`, else with an exclusive `wx` create. Works in a folder that is not a git repo |
 | `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 |
@@ -757,6 +758,7 @@ erDiagram
         TEXT metadata "JSON blob"
         TEXT awaiting_input_since "ISO 8601 or NULL — set by waiting Notifications"
         TEXT awaiting_reason "notification|stop|session_start|interrupted or NULL"
+        TEXT pinned_at "ISO 8601 or NULL — pinned to the top of its workspace's sidebar list"
         TEXT source "Data source — 'local' or a remote source id; NOT NULL DEFAULT 'local'"
     }
 
@@ -1064,7 +1066,7 @@ flowchart TD
 - Uses Node.js `http` module directly — no dependencies.
 - Resolution order is **env override → discovery file → default**:
   - `CLAUDE_DASHBOARD_PORT` forces a single target (no fan-out, no discovery).
-  - Otherwise `server/lib/server-info.js` reads `~/.claude/.agenthub.json`, prunes dead-PID entries, and returns one live `port` per unique `dataDir` (lowest port wins when two instances share `~/.claude/agenthub`). The handler POSTs to each returned port in parallel. The other instance learns of a lane the hooks moved through `broadcastForeignLaneChanges` (`server/routes/lanes.js`): every `DASHBOARD_LANE_SYNC_MS` (2 s) it reads `PRAGMA data_version`, which moves only on another connection's commit, and re-broadcasts each lane whose `updated_at` changed (and `removed` for a vanished one) to its own browsers. Sessions and events are not re-broadcast this way — a page on that instance shows them on its next fetch.
+  - Otherwise `server/lib/server-info.js` reads `~/.claude/.agenthub.json`, prunes dead-PID entries, and returns one live `port` per unique `dataDir` (lowest port wins when two instances share `~/.claude/agenthub`). The handler POSTs to each returned port in parallel. The other instance learns of a lane the hooks moved through `broadcastForeignLaneChanges` (`server/routes/lanes.js`): every `DASHBOARD_LANE_SYNC_MS` (2 s) — while `peersSharingDataDir()` finds another live dashboard on its data dir, which it checks every 30 s — it reads `PRAGMA data_version`, which moves only on another connection's commit, and re-broadcasts each lane whose `updated_at` changed (and `removed` for a vanished one) to its own browsers. Sessions and events are not re-broadcast this way — a page on that instance shows them on its next fetch.
   - If neither yields anything, the handler falls back to `4820`.
 - Per-target promises never reject — a dead listener can't starve the others, and the handler can wait on `Promise.all` for clean exit timing.
 
@@ -1221,7 +1223,12 @@ common "nothing changed" tick is just a handful of `stat` calls), funnels them
 through the same `parseSessionFile` + `importSession` pipeline as every other
 path, and broadcasts `session_created` for newly imported sessions /
 `session_updated` for grown ones — the same events hooks emit, so the UI
-refreshes live. All timers and watchers are `unref`'d and best-effort; nothing
+refreshes live. Two kinds of transcript are not re-parsed: one whose session
+hooks are feeding **live** (status `active`, newest event a hook's, a hook
+within `DASHBOARD_SYNC_LIVE_HOOK_MS`, default 5 min) is left until it goes
+quiet or ends — then caught up once — and one whose session a hook created
+(no `imported` flag, which `importSession` skips anyway) only has its durable
+snapshot refreshed, never a parse. All timers and watchers are `unref`'d and best-effort; nothing
 here blocks shutdown or can take down the server.
 
 ### Upload request sequence
@@ -1577,7 +1584,11 @@ re-point if that changes.
 `DASHBOARD_CODEX_POLL_MS` beat, a first pass over every journal in the
 background at startup). Each file's read offset and parse state live in the
 `codex_rollouts` table, so an unchanged file is never re-read and a grown one is
-read from where it stopped. `token_count` events are summed per `turn_context`
+read from where it stopped (a pass loads every row's size/mtime in one query).
+The first pass and one every five minutes walk every journal; the poll's other
+passes stat only the two newest day folders plus the journals the table saw
+written in the last hour (or not yet read to the end), so a thread resumed
+after an hour's quiet in an older folder is picked up by the next full pass. `token_count` events are summed per `turn_context`
 model — `input_tokens` includes `cached_input_tokens` (stored as input − cached
 plus cache_read) and `output_tokens` includes reasoning. A **fork** copies its
 parent's whole history into its own file, token events included, so every total
@@ -1652,7 +1663,9 @@ the binary's own proto descriptors.
 
 **Sessions and tokens** (`server/lib/antigravity-usage.js`,
 `startAntigravityUsagePoll`, every `DASHBOARD_ANTIGRAVITY_POLL_MS`, default
-15000, `0` disables). agy writes one SQLite file per conversation,
+15000, `0` disables; after a pass that read nothing, wrote nothing and left no
+fresh session to settle it slows to once a minute until one finds work —
+`server/lib/backoff-poll.js`). agy writes one SQLite file per conversation,
 `~/.gemini/antigravity-cli/conversations/<conversation id>.db`. Each is opened
 read-only whenever its mtime (or its non-empty `-wal`'s) changes;
 `antigravity_conversations` holds the mtime read, so a session the user deleted
@@ -1741,7 +1754,8 @@ is ever inferred.
 ## Cursor Sessions
 
 `server/lib/cursor-usage.js` (`startCursorUsagePoll`, every
-`DASHBOARD_CURSOR_POLL_MS`, default 15000, `0` disables) reads the agent
+`DASHBOARD_CURSOR_POLL_MS`, default 15000, `0` disables; idle passes slow it to
+once a minute like the Antigravity poll) 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
@@ -2223,7 +2237,7 @@ sequenceDiagram
 | Component | Responsibility |
 | --- | --- |
 | **`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/update-scheduler.js`** | Ticks the lib every `DASHBOARD_UPDATE_CHECK_INTERVAL_MS` (default 3 600 000 = 1 h, floor 60 000). A tick with no `/ws` browser connected (`getConnectionCount`) is skipped, and the first browser to connect afterwards (`onConnection` in `server/websocket.js`) gets one check 3 s later if the last one is older than the interval; the manual `POST /api/updates/check` is unaffected. 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 (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. |
@@ -2244,6 +2258,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"
@@ -2309,6 +2324,7 @@ The same shape is used by `GET /status`, `POST /check`, and the `update_status`
 | 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
@@ -2321,7 +2337,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`, which appends the new server's stdout/stderr to `data/agenthub-server.log` like `agenthub start` (it used to discard them, so a crash after an update left no stack trace). 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).
 
 ---
 
@@ -2352,7 +2368,7 @@ graph TD
         SHELL["Sagi.tsx<br/>shell: open/closed state,<br/>⌘B / Esc, reduced-motion,<br/>navigation"]
         AVATAR["SagiAvatar.tsx<br/>SVG mascot; data-mood drives CSS;<br/>cursor-tracking pupils"]
         BUBBLE["SpeechBubble.tsx<br/>bubble"]
-        PANEL["SagiPanel.tsx<br/>status + quick actions + Ask box"]
+        PANEL["PetChat.tsx + SagiInfo.tsx<br/>the chat window: status strip, Needs you,<br/>Mute / Clear alerts, local answers, AI chat"]
         CSS["sagi.css<br/>keyframes + per-mood expressions"]
     end
 
@@ -2382,8 +2398,8 @@ flowchart LR
     SUB --> DERIVED["derived state<br/>{ mood, status, bubble }"]
     DERIVED --> AVATAR["SagiAvatar"]
     DERIVED --> BUBBLE["SpeechBubble"]
-    DERIVED --> PANEL["SagiPanel"]
-    PANEL -->|"unmatched Ask"| ENSURE["POST /api/lanes/ensure<br/>(adopt 'Sagi' lane, cwd = home)"]
+    DERIVED --> PANEL["PetChat (+ SagiInfo)"]
+    PANEL -->|"unmatched question"| ENSURE["POST /api/lanes/ensure<br/>(adopt 'Sagi' lane, cwd = home)"]
     ENSURE --> START["POST /api/run<br/>(spawn tmux-backed claude<br/>in Sagi lane, initialPrompt=…)"]
     START --> RUN["/run?laneId=…<br/>(existing Run page picks up<br/>the live run)"]
 
@@ -2399,16 +2415,17 @@ The mood state machine in `deriveMood` resolves to a single expression using a f
 
 | Component | Responsibility |
 | --- | --- |
-| **`brain.ts`** | Pure, framework-free core. Exposes a `WSMessage` reducer (`reduceSagi`) and a mood state machine (`deriveMood`) with the priority order `disconnected > worried > stuck > happy > thinking > watching > sleeping > idle`. The clock is injected and there are zero side effects, so the brain is fully unit-tested in isolation. |
-| **`useSagiBrain.ts`** | The **only** consumer of the global `eventBus`. Wires the pure brain to real timers (idle / sleep / stuck), the speech-bubble queue, mute, and clear-alerts. Produces the derived `{ mood, status, bubble }` the presentational components render. |
+| **`brain.ts`** | Pure, framework-free core. Exposes a `WSMessage` reducer (`reduceSagi`, which also returns the `subject` session a pulse is about — name, cwd, lane) and a mood state machine (`deriveMood`) with the priority order `disconnected > worried > stuck > happy > thinking > watching > sleeping > idle`. An error alerts on the transition INTO `error` only, and **Clear alerts** (`clearErrors`) moves the errored sessions into `dismissed`: their later updates, agent errors and failure events stay silent until the session goes active again or ends. `attentionOf` lists errored then waiting sessions by name; `MOMENT_OF_PULSE` maps each pulse to a pet animation. The clock is injected and there are zero side effects, so the brain is fully unit-tested in isolation. |
+| **`useSagiBrain.ts`** | The **only** consumer of the global `eventBus`. Wires the pure brain to real timers (idle / sleep / stuck), the speech bubble (naming the session it is about; the same pulse again within 8 s joins it as a count), the one-shot `moment` animation, a once-per-browser-session greeting, an idle fidget every minute or so, pat, mute, and clear-alerts (the dismissed ids persist in `localStorage` `agenthub.pet.dismissedErrors`, newest 200). The reducer runs outside React's updater so StrictMode never doubles a pulse. Produces `{ mood, status, attention, bubble, moment }`. |
 | **`SagiAvatar.tsx`** | Pure presentational SVG mascot. The `data-mood` attribute drives CSS; pupils track the cursor. Rendered at 90×90 px (`size` default, kept in sync with `SAGI_SIZE` in `useSagiPosition.ts`, which is the draggable button's real footprint) through a `viewBox` cropped to the artwork's measured bounding box instead of the exporter's padded `0 0 1280 1280` canvas. Path data is never rescaled, so `MAX_PUPIL_SHIFT` stays in the original 1280-unit space. The `transform-origin` values in `sagi.css` do **not**: an origin on an inner SVG element resolves against `transform-box: view-box`, whose 0,0 sits at the `viewBox` min (`253.5 106`), so those are mascot coordinates **minus that offset**. The root `.sagi-avatar` origin is a percentage on purpose — on the outermost `<svg>` a length would be measured against the 68 px CSS box, and the resulting ~9× overshoot turns every mood animation into a whole-avatar lurch. |
-| **`SpeechBubble.tsx`** | Pure presentational speech bubble. |
-| **`SagiPanel.tsx`** | Pure presentational panel: status readout + quick actions + the Ask box. |
-| **`Sagi.tsx`** | Shell component. Mounted once in `client/src/components/Layout.tsx` as a sibling of `UpdateNotifier`. Owns open/closed state, the `⌘B` / `Esc` shortcuts, reduced-motion detection, and navigation. |
-| **`intents.ts`** | Pure local Q&A over the cached status snapshot. Queries that don't match a local intent become a handoff: `Sagi.tsx` calls `POST /api/lanes/ensure` (adopting the "Sagi" lane whose cwd defaults to `$HOME`), then `POST /api/run` to spawn a fresh tmux-backed `claude` session in that lane with the prompt as its `initialPrompt`, then navigates to `/run?laneId=…&autostart=1` so the live run is observable. |
-| **`quips.ts`** | Pure mood → phrase pools. |
-| **`prefs.ts`** | `localStorage`-backed enabled / muted preferences with cross-tab sync. |
-| **`sagi.css`** | Keyframes and per-mood expressions; selected via the `data-mood` attribute. |
+| **`SpeechBubble.tsx`** | Pure presentational speech bubble: the line, the session(s) it is about, and an **Open** button for a single one (`workspaceHref` — its live pane, else its replay, else `/sessions/<id>`; never a resume). |
+| **`SagiInfo.tsx`** | Pure presentational pieces of the chat window: `PetNameButton` (click to rename — `agenthub.pet.names`, synced to the account) and `SagiInfo`, the status strip under the header — live / waiting / errored and the connection always shown; expanded (by default while something needs you) a **Needs you** list of errored/waiting sessions by name, Mute and Clear alerts. |
+| **`PetChat.tsx`** | The pet's whole UI — clicking the pet opens it (there is no separate panel): header (name, pat heart, Open in workspace, New chat, close), the `SagiInfo` strip, then the conversation. Before a chat runs, a question `intents.ts` can answer is answered in place (`onLocal`); anything else goes to the AI. Styled as a soft accent gradient with chat bubbles. The first message starts a session of the user's default AI tool (`agenthub.defaultTool`; Claude or Codex — any other tool still opens its pane in the workspace) in the "Sagi" workspace's first free tab; replies are read from the session's transcript every 1.5 s, and follow-ups and menu answers (`PaneMenuCard` — numbered menus and Claude's unnumbered folder-trust prompt alike) go through a `TerminalView` attached off-screen (`submitToRun`), so no new route exists. The chat is kept in `localStorage` (`agenthub.pet.chat`) while its pane lives, so closing and reopening the window continues it; **New chat** stops that session (`DELETE /api/run/:id?archive=1`, asking first only mid-reply); an ended pane is never resumed — the next message starts a new session. |
+| **`Sagi.tsx`** | Shell component. A pat (the chat's heart, a typed pat, or stroking the pet — four left/right turns of the pointer over it within 1.2 s) shows hearts and a line ON the pet, so it reads while the chat is open. Mounted once in `client/src/components/Layout.tsx` as a sibling of `UpdateNotifier`. Owns the chat's open/closed state, the `⌘B` / `Esc` shortcuts, reduced-motion detection, and navigation. |
+| **`intents.ts`** | Local Q&A over the cached status snapshot, in English and Vietnamese keywords, answering in the UI language and naming the sessions it counts (also: who are you, hello, thanks, pat). Queries that don't match a local intent go to `PetChat`'s AI session; with a default tool it cannot read back, `Sagi.tsx` instead calls `POST /api/lanes/ensure` (adopting the "Sagi" lane whose cwd defaults to `$HOME`), then `POST /api/run` to spawn a fresh tmux-backed `claude` session in that lane with the prompt as its `initialPrompt`, then navigates to `/run?laneId=…&autostart=1` so the live run is observable. |
+| **`quips.ts`** | Mood/pulse → phrase pools, plus greetings and pat lines, read from `settings:sagi.{quips,greet,pat}` so they follow the UI language. |
+| **`prefs.ts`** | `localStorage`-backed enabled / muted / pet / size / nickname preferences with cross-tab sync; `petName` = nickname, else the worn pet's own name, else Sagi. |
+| **`sagi.css`** | Keyframes and per-mood expressions (`data-mood`), plus the one-shot moments (`data-moment`: jump, wave, fail, wait, review) on Sagi's art and an uploaded image. |
 
 ### Touchpoints Outside the Folder
 
@@ -2420,7 +2437,7 @@ Sagi's only contact with the rest of the app is four light, additive touchpoints
 | `client/src/pages/Settings.tsx` | On/off toggle wired to `sagiPrefs` (`localStorage`). |
 | `client/src/pages/Run.tsx` | Consumes `?laneId=` to attach the page to the lane whose run Sagi just spawned. |
 | `server/routes/lanes.js` (`POST /api/lanes/ensure`) | Accepts a missing `cwd` and resolves it to `os.homedir()` so the mascot can adopt a stable "Sagi" lane. |
-| `client/src/i18n/locales/{en,vi}/settings.json` | `sagi.*` strings for the Settings toggle (zh / ko fall back to the hardcoded English defaults). |
+| `client/src/i18n/locales/{en,vi}/settings.json` | Every `sagi.*` string: the Settings toggle, the panel, the bubbles' quips, coalesced counts, greetings and Ask answers. |
 
 ---
 

INSTALL.md

@@ -1,6 +1,6 @@
 # Installation
 
-A step-by-step guide to get AgentHub — the local control surface for Claude Code agents — up and running on your machine, with optional sections for importing history and running in a container.
+The one install-and-setup guide for AgentHub — the local control surface for Claude Code agents: the plugin install, a checkout install, configuration, the database, importing history, and troubleshooting. (`SETUP.md` is only a pointer here now.)
 
 ## Fastest path — install it as a Claude Code plugin
 
@@ -17,17 +17,20 @@ on PATH — no clone, no `npm run setup`, no
 result and `/agenthub-open` to build the UI and get the URL.
 
 Requires Node **>= 22.5** (a plugin install has no native `better-sqlite3`, so
-the server stores data through `node:sqlite`). Full behavior, including the
-uninstall cleanup (`agenthub uninstall`), is in [`docs/PLUGINS.md`](docs/PLUGINS.md).
+the server stores data through `node:sqlite`), plus `git` and `tmux` from
+[Step 0](#step-0--system-packages). Full behavior, including the uninstall
+cleanup (`agenthub uninstall`), is in [`docs/PLUGINS.md`](docs/PLUGINS.md). If
+the dashboard never comes up, see
+[Plugin bootstrap never comes up](#plugin-bootstrap-never-comes-up).
 
 Follow the steps below instead when you want a checkout — to develop the
-dashboard, run it from source, or stay on Node 20.
+dashboard or run it from source.
 
 ## Requirements
 
 | Requirement | Version | Notes |
 |---|---|---|
-| Node.js | 20+ (22+ recommended) | Required for server and client |
+| Node.js | **22.5+** | Required for server and client (`node:sqlite`). Node 20 is end-of-life and unsupported |
 | npm | 9+ | Comes with Node.js |
 | Claude Code | 2.x+ | Required for hook integration |
 | Git | Any | Cloning the repository, and every lane operation (worktrees, branch/status reads) |
@@ -76,7 +79,7 @@ Check it:
 ```bash
 tmux -V          # e.g. tmux 3.4
 git --version
-node -v          # v20.x / v22.x / v24.x
+node -v          # v22.5+ / v24.x
 ```
 
 Once the server is up you can ask it directly — this is the same probe the
@@ -113,8 +116,8 @@ brew install node git tmux       # Node >= 22.5 for the plugin install (nvm work
 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc   # where the plugin puts `agenthub`
 ```
 
-- **Node:** a plugin install needs **>= 22.5** (it stores data through
-  `node:sqlite`); a checkout still runs on Node 20. The `agenthub` launcher
+- **Node:** **>= 22.5** (the plugin stores data through `node:sqlite`; a
+  checkout needs the same). The `agenthub` launcher
   pins the node that installed it and falls back to `node` on `PATH` when a
   `brew upgrade` or `nvm` switch deletes that binary.
 - **Starts at login once you turn it on (LaunchAgent).** Off by default; with
@@ -172,24 +175,20 @@ cd AgentHub
 ## Step 2 — Install dependencies
 
 ```bash
-npm run setup
+npm run setup        # or: make setup
 ```
 
-This installs all server and client dependencies, plus the VS Code extension, and links the `agenthub` CLI.
+This runs `npm install` (whose `postinstall` hook installs the client's
+dependencies in `client/`), installs `client/` once more explicitly, and links
+the `agenthub` CLI (`npm link`; if that has no permission it prints how to link
+it by hand). A plain `npm install` is enough to build and run the dashboard —
+only the CLI link is missing.
 
-A plain root install already covers server **and** client — a `postinstall` hook installs the client dependencies automatically, so this alone is enough to build and run the dashboard:
+With `--ignore-scripts` the `postinstall` hook is skipped; install the client
+yourself with `npm --prefix client install`.
 
-```bash
-npm install
-```
-
-`npm run setup` additionally installs the VS Code extension and links the `agenthub` CLI. (If you install with `--ignore-scripts`, the `postinstall` hook is skipped — run `cd client && npm install` manually in that case.)
-
-Or via Makefile:
-
-```bash
-make setup
-```
+`better-sqlite3` gyp/compile warnings here are harmless — see
+[Troubleshooting](#better-sqlite3-errors-during-npm-install--npm-run-setup).
 
 ---
 
@@ -234,7 +233,7 @@ After starting a Claude Code session, you should see:
 - **Dashboard** — stats updating in real-time
 - **Settings page** — data export and cleanup tools on the Dashboard tab; Claude Code's model pricing rules, hook configuration status and CLAUDE_HOME on **Settings → Claude Code → Overview**
 
-If nothing appears after 30 seconds, see [SETUP.md](./SETUP.md#troubleshooting).
+If nothing appears after 30 seconds, see [Troubleshooting](#no-sessions-appearing-after-starting-claude-code).
 
 ### PWA install (optional)
 
@@ -246,57 +245,110 @@ The dashboard is a Progressive Web App. After opening it in a supported browser
 
 ---
 
-## Step 5 — (Optional) Import existing Claude Code history
+## Step 5 — (Optional) Importing existing Claude Code history
 
-The server **automatically imports** every session under
-`~/.claude/projects/` on startup, so if you've used Claude Code on this
-machine before, your historical sessions, agents, events, token counts,
-and cost totals should already be visible in the Sessions list.
+The dashboard automatically imports sessions from `~/.claude/projects/` on
+**every startup**, so if Claude Code has been used on this machine, you'll
+see history immediately after the first launch. If you need to bring in
+history from another machine, from a backup, or just force a rescan, use
+**Settings → Import History** in the UI — it's a guided, drag-and-drop
+experience with live progress.
 
-To bring in history from another machine, a backup, or a `.tar.gz`
-archive a teammate sent you, use **Settings → Import History** in the
-UI. It supports three modes:
+### Pick the right mode
 
 ```mermaid
-flowchart LR
-    UI["Settings →<br/>Import History"] --> M1["Rescan default folder<br/>~/.claude/projects"]
-    UI --> M2["Scan a folder<br/>any absolute path"]
-    UI --> M3["Upload files<br/>.jsonl / .zip / .tar.gz / .gz"]
-    M1 --> P["Same parser as live<br/>hook ingestion"]
-    M2 --> P
-    M3 --> P
-    P --> DB[("SQLite<br/>sessions + tokens + cost")]
+flowchart TD
+    Q["Where is the history?"] --> Q1{Is it on this machine<br/>under ~/.claude/projects?}
+    Q1 -->|yes, and I just want<br/>to re-scan| M1["Mode: Rescan default folder<br/>one click"]
+    Q1 -->|yes, but in another folder<br/>on this machine| M2["Mode: Scan a folder<br/>paste the absolute path"]
+    Q1 -->|no — it's on another machine<br/>or in an archive file| M3["Mode: Upload files<br/>drag-drop JSONL or archive"]
 
-    style UI fill:#a855f7,stroke:#c084fc,color:#fff
-    style P fill:#f59e0b,stroke:#fbbf24,color:#000
-    style DB fill:#10b981,stroke:#34d399,color:#fff
+    M3 --> PREP["Archive source:<br/>tar -czf claude-history.tar.gz<br/>-C ~/.claude projects"]
+
+    style M1 fill:#10b981,stroke:#34d399,color:#fff
+    style M2 fill:#f59e0b,stroke:#fbbf24,color:#000
+    style M3 fill:#a855f7,stroke:#c084fc,color:#fff
 ```
 
-Re-imports are idempotent: sessions are deduplicated by UUID and
-compaction baselines preserve pre-compaction token totals, so running
-the importer twice never double-counts tokens or cost.
+### Step-by-step: moving history from one machine to another
 
-Verify it worked by opening the **Analytics** page and checking that
-per-model token totals and estimated cost look correct. Full walkthrough
-with per-OS archive commands in
-[SETUP.md → Importing existing Claude Code history](./SETUP.md#importing-existing-claude-code-history).
-### Optional: tune import limits
+**On the source machine**, bundle the projects folder:
 
-If you regularly import very large archives, these environment variables
-can be raised (the defaults are generous for typical use):
+```bash
+# macOS / Linux
+tar -czf claude-history.tar.gz -C ~/.claude projects
 
-| Variable                          | Default | Purpose                                                     |
-| --------------------------------- | ------- | ----------------------------------------------------------- |
-| `AGENTHUB_IMPORT_MAX_BYTES`           | 1 GB    | Maximum size per uploaded file                              |
-| `AGENTHUB_IMPORT_MAX_FILES`           | 2000    | Maximum files per upload request                            |
-| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES`   | 4 GB    | Ceiling on uncompressed bytes per archive (zip-bomb guard)  |
+# Windows (PowerShell, via built-in tar)
+tar -czf claude-history.tar.gz -C "$env:USERPROFILE\.claude" projects
+```
 
-Set them before `npm run dev` or `npm start`:
+Transfer the resulting `claude-history.tar.gz` to the destination machine
+however you like — AirDrop, `scp`, USB, cloud storage.
+
+**On the destination machine**, in the dashboard:
+
+1. Open **Settings → Import History**.
+2. Pick **Upload files** (the third tab).
+3. Drag the archive onto the drop zone.
+4. Click **Upload & Import** and watch the progress.
+5. When the green result card appears, open **Analytics → Cost** to confirm
+   per-model token totals and estimated cost.
+
+### Supported inputs
+
+Any of the following can be dropped onto the upload zone or found inside a
+folder given to **Scan a folder**:
+
+- `.jsonl` — session transcripts
+- `.meta.json` — subagent metadata sidecars
+- `.zip` — extracted with path-traversal protection
+- `.tar`, `.tar.gz`, `.tgz` — extracted via the `tar` package
+- `.gz` — single gzipped JSONL (streaming-decompressed)
+
+### Accuracy guarantees
+
+- **Idempotent** — re-importing never double-counts. Sessions are
+  deduplicated by UUID.
+- **Cost-preserving** — the `token_usage` table uses `baseline_*` columns
+  to preserve pre-compaction token totals, so re-ingesting a compacted
+  transcript never erases historical cost.
+- **Same parser as live** — `parseSessionFile` + `importSession` is the
+  single source of truth for both hook-driven ingestion and manual
+  import, so imported numbers match captured numbers exactly.
+
+### Safety
+
+Archive extraction is hardened against path traversal and archive bombs.
+The defaults are generous for real-world transcripts but tight enough to
+stop obvious attacks. If you regularly import very large archives, raise them
+before `npm run dev` or `npm start` (also listed under
+[Environment variables](#environment-variables)):
+
+| Variable                            | Default | Purpose                                                    |
+| ----------------------------------- | ------- | ---------------------------------------------------------- |
+| `AGENTHUB_IMPORT_MAX_BYTES`         | 1 GB    | Maximum size per uploaded file                             |
+| `AGENTHUB_IMPORT_MAX_FILES`         | 2000    | Maximum files per upload request                           |
+| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES` | 4 GB    | Ceiling on uncompressed bytes per archive (zip-bomb guard) |
 
 ```bash
 AGENTHUB_IMPORT_MAX_EXTRACT_BYTES=17179869184 npm start   # allow 16 GB extraction
 ```
 
+### CLI alternative
+
+For scripts and automation, the same logic runs from the terminal:
+
+```bash
+# Import (or re-import) everything under ~/.claude/projects
+npm run import-history
+
+# Dry run — show what would be imported without writing
+node scripts/import-history.js --dry-run
+
+# Scope to a single project dir
+node scripts/import-history.js --project my-project
+```
+
 ---
 
 ## Production mode
@@ -328,44 +380,260 @@ and, for plugin installs, [`docs/PLUGINS.md` → Auto-start on boot](docs/PLUGIN
 
 ---
 
-## Optional: Agent extension packs
+## How it works
 
-This repository includes extension packs for both Claude Code and Codex.
+AgentHub integrates with Claude Code through its native hook system. When Claude Code performs any action (session start, tool use, turn completion, subagent finish, session exit), it fires a hook that calls a small Node.js script bundled with this project. That script forwards the event over HTTP to the dashboard server, which stores it in SQLite and broadcasts it to the browser over WebSocket.
 
-- Claude Code loads project extensions from:
+```
+Claude Code  →  hook fires  →  hook-handler.js  →  POST /api/hooks/event
+                                                         ↓
+Browser  ←  WebSocket broadcast  ←  Express server  ←  SQLite
+```
+
+No extra Claude Code configuration is required in the normal host-run path — when you start the dashboard with `npm run dev` or `npm start`, the server configures the hooks automatically on startup (or, with the `agenthub` plugin enabled in `~/.claude/settings.json`, removes the checkout's copies — the plugin's own hooks already run, and both would post every event twice). Container deployments are the exception: after the container is up, run `npm run install-hooks` on the host so Claude Code points at `http://localhost:4820`.
+
+---
+
+## Configuration
+
+### Hook auto-installation
+
+When the dashboard is running directly on the host, the server writes the following to `~/.claude/settings.json` every time it starts:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionStart" }] }],
+    "PreToolUse":   [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PreToolUse" }] }],
+    "PostToolUse":  [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PostToolUse" }] }],
+    "Stop":         [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Stop" }] }],
+    "SubagentStop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SubagentStop" }] }],
+    "Notification": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Notification" }] }],
+    "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionEnd" }] }]
+  }
+}
+```
+
+> [!NOTE]
+> Note: `SessionStart` and `SessionEnd` hooks do not support the `matcher` field — they fire unconditionally on every session start and exit.
+
+Existing hooks in that file are preserved. The dashboard only adds or updates entries that contain `hook-handler.js`.
+
+To re-run hook installation manually:
+
+```bash
+npm run install-hooks
+```
+
+> [!TIP]
+> Container note: if you run the dashboard inside a container (a Dev Container, Codespaces, or your own image), do not install hooks from in there — the hook path a container writes points at the container filesystem, not the host. Run `npm run install-hooks` on the host instead. As a safeguard (issue #193) the installer **detects container execution and refuses to run** (exiting non-zero) so it can never poison a bind-mounted host `~/.claude`. If Claude Code itself genuinely runs inside that container, override with `AGENTHUB_ALLOW_CONTAINER_HOOKS=1 npm run install-hooks`.
+
+> [!NOTE]
+> Prefer a ready-made dev environment? This repo ships an **optional** Dev Container (`.devcontainer/`) for VS Code / GitHub Codespaces — Node 22, native build tools for `better-sqlite3`, Python, and ports `4820`/`5173` preconfigured. It's purely opt-in and changes nothing for host-based development. See [`.devcontainer/README.md`](.devcontainer/README.md). (Hooks remain host-side there too.)
+
+### Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `DASHBOARD_PORT` | `4820` | Port the Express server listens on |
+| `CLAUDE_DASHBOARD_PORT` | `4820` | Port the hook handler uses when posting events to the dashboard |
+| `DASHBOARD_DB_PATH` | `data/dashboard.db` | Path to the SQLite database file |
+| `NODE_ENV` | `development` | Set to `production` to serve built client |
+| `DASHBOARD_CLIENT_DIST` | `client/dist` | Directory the built UI is served from in production. Set by the `agenthub` plugin bootstrap to its own runtime dir, because the plugin cache is replaced on every update |
+| `AGENTHUB_IMPORT_MAX_BYTES` | `1073741824` (1 GB) | Maximum size per uploaded file on `/api/import/upload` |
+| `AGENTHUB_IMPORT_MAX_FILES` | `2000` | Maximum number of files per upload request |
+| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES` | `4294967296` (4 GB) | Maximum uncompressed bytes any single archive is allowed to expand to (zip-bomb defense) |
+| `DASHBOARD_DATA_DIR` | `~/.claude/agenthub` | AgentHub's data dir; a plugin install keeps its runtime (deps, UI build, logs) in `runtime/` under it |
+
+Example with a custom port:
+
+```bash
+DASHBOARD_PORT=9000 npm run dev
+```
+
+> [!NOTE]
+> You usually do **not** need to set `DASHBOARD_PORT` manually. `npm run dev` is wrapped by `scripts/dev.js`, which probes both `127.0.0.1` and `::1` (so an SSH `LocalForward` bound to one loopback can't slip past) and picks the first free port in `4820–4859` automatically. The chosen port is propagated to the Vite dev proxy via `DASHBOARD_PORT`, and the Express server writes it to `~/.claude/.agenthub.json` so the Claude Code hook handler discovers it without any env var.
+>
+> Multiple dashboards can run side by side — for example two `npm run dev` checkouts, or `npm run dev` alongside `npm start`. Each one appends its `{port, pid, startedAt}` entry to the discovery file, and `scripts/hook-handler.js` fan-outs every hook event to every live entry, so both UIs keep their real-time stream.
+>
+> Setting `CLAUDE_DASHBOARD_PORT=N` overrides discovery entirely and forces the hook handler to a single port — useful for tests and container setups where the in-process discovery file isn't reachable from the host.
+>
+> If you bypass the picker (e.g. `npm run dev:raw`, container builds, or anything else that calls `node server/index.js` directly), make sure your client is built / proxied against the port the server actually bound.
+
+### Agent extension setup (Claude Code + Codex)
+
+This repository ships extension files for both agent ecosystems:
+
+- Claude Code:
   - `CLAUDE.md`
-  - `.claude/rules/`
-  - `skills/` (shipped as the `agenthub` plugin's skills)
-- Codex project packs live under `.codex/`:
+  - `.claude/rules/*`
+  - `skills/*` (the `agenthub` plugin's own skills)
+- Codex:
   - `AGENTS.md`
-  - `.codex/rules/`
-  - `.codex/agents/`
-  - `.codex/skills/`
+  - `.codex/config.toml`
+  - `.codex/rules/default.rules`
+  - `.codex/agents/*`
+  - `.codex/skills/*`
 
 See [`.codex/README.md`](./.codex/README.md) for Codex extension details.
 
+### PWA configuration (optional)
+
+The dashboard ships as a Progressive Web App. No configuration is required — its manifest and service worker are included out of the box.
+
+**Customising the manifest:** Edit `client/public/manifest.json`. Common fields to change:
+
+- `name` / `short_name` — displayed on the home screen / dock
+- `theme_color` — address bar / title bar tint (default: `#6366f1`)
+- `background_color` — splash screen background
+- `start_url` — entry point when launched from home screen
+
+**Updating the service worker cache:** The SW has a `CACHE_NAME` constant (e.g. `dashboard-v2`). After deploying new assets, bump the version string to force browsers to re-fetch — though for the dashboard this is rarely needed: hashed `/assets/*` URLs are immutable per build, everything else is fetched network-first with cache fallback, and a `controllerchange` listener in the client reloads the page exactly once when a new SW takes over, so a rebuild propagates without a hard refresh.
+
+**Browser support:** PWA install prompts appear in Chrome 107+, Edge 107+, and Firefox 110+ (desktop and Android). Safari supports `apple-mobile-web-app-capable` for iOS home-screen mode but does not show an install banner.
+
+**Verifying PWA status:** Open DevTools → Application → Manifest to confirm the manifest loads. Check the Service Workers section to verify the SW is registered and active. The Lighthouse PWA audit should pass all core checks.
+
+---
+
+## Database
+
+The SQLite database is created automatically on first run (`data/dashboard.db` in a checkout, unless `DASHBOARD_DB_PATH` says otherwise). The directory is created if it does not exist. The database uses WAL mode for concurrent reads and foreign keys for referential integrity.
+
+### Clear all data
+
+To remove all sessions, agents, events, and token usage (useful after running seed data or for a clean start):
+
+```bash
+npm run clear-data
+```
+
+### Data management via Settings page
+
+The Settings page (`/settings`) provides a UI for the following. **Model Pricing**
+and **Hook Configuration** are not on its Dashboard tab: they sit under the
+Claude Code tab's **Overview** (Settings → Claude Code → Overview), beside
+CLAUDE_HOME; Codex (its Overview) and Antigravity have their own pricing and
+hooks in their own tabs.
+
+- **Model Pricing** — view and edit per-model cost rates, reset to defaults, add custom models
+- **Hook Configuration** — check which hooks are installed and reinstall them
+- **Data Export** — download all sessions, agents, events, and pricing as a JSON file
+- **Session Cleanup** — abandon stale active sessions after N hours, purge old completed sessions after N days
+- **Clear All Data** — remove all sessions, agents, events, and token usage
+- **Data Management** and **About** sections render with loading placeholders while server info is being fetched, so the page is always fully navigable
+
+### Seed demo data
+
+To populate the dashboard with sample sessions, agents, and events for UI exploration:
+
+```bash
+npm run seed
+```
+
+---
+
+## Scripts reference
+
+| Script | Command | Description |
+|---|---|---|
+| `setup` | `npm run setup` | Install all dependencies (server + client) |
+| `dev` | `npm run dev` | Start server + client in development mode |
+| `start` | `npm start` | Start server in production mode |
+| `build` | `npm run build` | Build the React client to `client/dist/` |
+| `install-hooks` | `npm run install-hooks` | Write Claude Code hooks to `~/.claude/settings.json` |
+| `clear-data` | `npm run clear-data` | Delete all data from the database |
+| `seed` | `npm run seed` | Insert demo sessions/agents/events |
+| `import-history` | `npm run import-history` | Import legacy sessions from `~/.claude/` (also runs on startup) |
+| `claude` | Claude CLI | Uses `CLAUDE.md`, `.claude/rules`, and `.claude/skills` automatically |
+| `test` | `npm test` | Run all server and client tests |
+| `test:server` | `npm run test:server` | Run server integration tests only |
+| `test:client` | `npm run test:client` | Run client unit tests only |
+| `format` | `npm run format` | Format all files with Prettier |
+| `format:check` | `npm run format:check` | Check formatting without writing |
+
+---
+
+## Makefile targets
+
+All npm scripts are mirrored as `make` targets for convenience. Run `make help` to list them:
+
+```bash
+make help
+```
+
+Commonly used targets:
+
+| Make target | Equivalent npm command | Description |
+|---|---|---|
+| `make setup` | `npm run setup` | Install all dependencies (root + client) |
+| `make dev` | `npm run dev` | Start server + client in watch mode |
+| `make build` | `npm run build` | Build the React client for production |
+| `make start` | `npm start` | Start the production server |
+| `make prod` | `npm run build && npm start` | Build then start in one step |
+| `make test` | `npm test` | Run all tests (server + client) |
+| `make test-server` | `npm run test:server` | Run server tests only |
+| `make test-client` | `npm run test:client` | Run client tests only |
+| `make format` | `npm run format` | Format all files with Prettier |
+| `make format-check` | `npm run format:check` | Check formatting without writing |
+| `make seed` | `npm run seed` | Load demo data |
+| `make clear-data` | `npm run clear-data` | Delete all data rows |
+
 ---
 
 ## Troubleshooting
 
-### `npm run setup` shows `better-sqlite3` errors
+### Plugin bootstrap never comes up
 
-This is expected and **non-fatal**. `better-sqlite3` is a native C++ module listed as an optional dependency. If prebuilt binaries are not available for your Node version or platform, npm will print gyp/compilation errors but still complete successfully.
+The plugin's `SessionStart` hook only checks a fast path and hands the real
+work (npm install, UI build, server start) to a detached background worker, so
+a failure there does not show in the session. When the worker's last run
+failed, the next session start prints a one-time **AgentHub:** message naming
+the log to read. Everything is logged under `~/.claude/agenthub/runtime/`:
 
-At runtime the server uses this fallback chain:
+| File | What it holds |
+|---|---|
+| `bootstrap.log` | Each bootstrap step and why it stopped (Node too old, install failed, superseded build, …) |
+| `npm-install.log` | npm's output for the runtime dependency install |
+| `client-build.log` | The dashboard UI build (the API still works when only this fails) |
+| `server.log` | The server's own output, when it was started detached |
+| `last-failure.json` | The last failure the session-start message reports (removed once a bootstrap succeeds) |
 
-1. **`better-sqlite3`** — used when prebuilt binaries are available (Node 20/22/24 on Windows x64, macOS arm64/x64, Linux x64/arm64)
-2. **`node:sqlite`** — Node.js built-in SQLite module, used automatically on Node 22+ when `better-sqlite3` is unavailable
+Then run `/agenthub-doctor` from Claude Code — it checks Node, the runtime
+dependencies, the server and the service unit, and names the fix for each
+failing row. `/agenthub-update` re-runs the bootstrap in the foreground with its
+output visible. The most common causes: Node older than 22.5 (`node -v` in the
+shell Claude Code was started from), no network or a proxy blocking the npm
+registry (`npm-install.log`), and a port held by another program (`server.log`,
+see [Port 4820 already in use](#port-4820-already-in-use)).
 
-If you see an error box at startup saying *"SQLite backend not available"*, either:
+### `better-sqlite3` errors during `npm install` / `npm run setup`
 
-- **Upgrade to Node.js 22+** (recommended — zero native dependencies needed), or
-- **Install build tools** so `better-sqlite3` can compile from source:
-  - **Windows:** `npm install -g windows-build-tools` or install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the C++ workload
-  - **macOS:** `xcode-select --install`
-  - **Linux:** `sudo apt install python3 make g++` (Debian/Ubuntu) or equivalent
+Only a **checkout** install sees these — the plugin installs with
+`--ignore-scripts` and never builds `better-sqlite3`. They are **harmless**:
+`better-sqlite3` is an optional dependency, and when it cannot be built npm
+skips it and the server uses Node's built-in `node:sqlite` (Node 22.5+). You do
+**not** need Python, Visual Studio Build Tools or a C++ compiler.
 
-  Then run: `npm rebuild better-sqlite3`
+To build it anyway (it is used when present), install a toolchain and run
+`npm rebuild better-sqlite3`:
+
+- **Windows:** [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the C++ workload
+- **macOS:** `xcode-select --install`
+- **Linux:** `sudo apt install python3 make g++` (Debian/Ubuntu) or equivalent
+
+### "SQLite backend not available" error on startup
+
+Neither `better-sqlite3` nor `node:sqlite` could be loaded — almost always a
+Node older than 22.5. Upgrade Node.
+
+### Database is locked / busy errors
+
+The SQLite database uses WAL mode with a 5-second busy timeout. If you see lock errors:
+
+- Ensure only one dashboard server instance is running
+- Check for zombie `node server/index.js` processes: `ps aux | grep server/index`
+- Delete `data/dashboard.db-wal` and `data/dashboard.db-shm` if the server was killed uncleanly, then restart
 
 ### `npm run dev` fails immediately
 
@@ -375,7 +643,7 @@ Ensure both server and client dependencies are installed:
 npm run setup
 ```
 
-If the error mentions a missing module like `express` or `react`, dependencies may be incomplete. Delete `node_modules` in both root and `client/`, then re-run setup:
+If the error mentions a missing module like `express` or `react`, dependencies may be incomplete. Delete `node_modules` in both the root and `client/`, then re-run setup:
 
 ```bash
 rm -rf node_modules client/node_modules
@@ -409,9 +677,66 @@ that case.
 
 ### No sessions appearing after starting Claude Code
 
-See [SETUP.md — Troubleshooting](./SETUP.md#troubleshooting) for detailed hook debugging steps.
+**Check 1 — Is the server running?**
 
----
+```bash
+curl http://localhost:4820/api/health
+# Expected: {"status":"ok","timestamp":"..."}
+```
+
+**Check 2 — Are hooks installed?**
+
+With the plugin, its hooks come with it — run `/agenthub-doctor` instead. For a
+checkout, open `~/.claude/settings.json` and confirm it contains a `hooks`
+section with entries referencing `hook-handler.js`. If not, run:
+
+```bash
+npm run install-hooks
+```
+
+**Check 3 — Did you start a new Claude Code session after the server started?**
+
+Hooks only apply to sessions started after installation. Restart Claude Code.
+
+**Check 4 — Is Node.js in PATH when Claude Code runs hooks?**
+
+On some systems, the shell environment when Claude Code fires hooks may not include the full PATH. Test with:
+
+```bash
+node --version
+```
+
+If Node.js is not found, use the full path to `node` in the hook command. Edit `scripts/install-hooks.js`, replace `node` with the absolute path (e.g. `/usr/local/bin/node`), and re-run `npm run install-hooks`.
+
+### Dashboard shows "Disconnected" in the sidebar
+
+The WebSocket connection to the server failed. Ensure the server is running:
+
+```bash
+npm run dev
+```
+
+The client will automatically reconnect every 2 seconds once the server is available.
+
+### Port 4820 already in use
+
+When another program holds the port, the server stops with
+`Port 4820 is already in use by another program…` (a running AgentHub there is
+detected and simply reused). Pick another port:
+
+```bash
+DASHBOARD_PORT=4821 npm start      # or: DASHBOARD_PORT=4821 npm run dev
+```
+
+The Vite dev proxy and the Claude Code hooks follow the port on their own
+(`client/vite.config.ts` reads `DASHBOARD_PORT`; the server publishes the port it bound).
+
+And make sure Claude Code posts hooks to the new port:
+
+```bash
+CLAUDE_DASHBOARD_PORT=4821 claude
+# or edit scripts/hook-handler.js and change the default port
+```
 
 ## Ports
 

SETUP.md

@@ -1,422 +1,14 @@
 # Setup Guide
 
-A comprehensive guide to setting up and configuring the Agent Dashboard, including how it integrates with Claude Code, environment variables, container deployment, and troubleshooting common issues.
-
-## How it works
-
-Agent Dashboard integrates with Claude Code through its native hook system. When Claude Code performs any action (session start, tool use, turn completion, subagent finish, session exit), it fires a hook that calls a small Node.js script bundled with this project. That script forwards the event over HTTP to the dashboard server, which stores it in SQLite and broadcasts it to the browser over WebSocket.
-
-```
-Claude Code  →  hook fires  →  hook-handler.js  →  POST /api/hooks/event
-                                                         ↓
-Browser  ←  WebSocket broadcast  ←  Express server  ←  SQLite
-```
-
-No extra Claude Code configuration is required in the normal host-run path — when you start the dashboard with `npm run dev` or `npm start`, the server configures the hooks automatically on startup (or, with the `agenthub` plugin enabled in `~/.claude/settings.json`, removes the checkout's copies — the plugin's own hooks already run, and both would post every event twice). Container deployments are the exception: after the container is up, run `npm run install-hooks` on the host so Claude Code points at `http://localhost:4820`.
-
----
-
-## Configuration
-
-### Hook auto-installation
-
-When the dashboard is running directly on the host, the server writes the following to `~/.claude/settings.json` every time it starts:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionStart" }] }],
-    "PreToolUse":   [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PreToolUse" }] }],
-    "PostToolUse":  [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" PostToolUse" }] }],
-    "Stop":         [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Stop" }] }],
-    "SubagentStop": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SubagentStop" }] }],
-    "Notification": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" Notification" }] }],
-    "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "node \"/path/to/scripts/hook-handler.js\" SessionEnd" }] }]
-  }
-}
-```
-
-> [!NOTE]
-> Note: `SessionStart` and `SessionEnd` hooks do not support the `matcher` field — they fire unconditionally on every session start and exit.
-
-Existing hooks in that file are preserved. The dashboard only adds or updates entries that contain `hook-handler.js`.
-
-To re-run hook installation manually:
-
-```bash
-npm run install-hooks
-```
-
-> [!TIP]
-> Container note: if you run the dashboard inside a container (a Dev Container, Codespaces, or your own image), do not install hooks from in there — the hook path a container writes points at the container filesystem, not the host. Run `npm run install-hooks` on the host instead. As a safeguard (issue #193) the installer **detects container execution and refuses to run** (exiting non-zero) so it can never poison a bind-mounted host `~/.claude`. If Claude Code itself genuinely runs inside that container, override with `AGENTHUB_ALLOW_CONTAINER_HOOKS=1 npm run install-hooks`.
-
-> [!NOTE]
-> Prefer a ready-made dev environment? This repo ships an **optional** Dev Container (`.devcontainer/`) for VS Code / GitHub Codespaces — Node 22, native build tools for `better-sqlite3`, Python, and ports `4820`/`5173` preconfigured. It's purely opt-in and changes nothing for host-based development. See [`.devcontainer/README.md`](.devcontainer/README.md). (Hooks remain host-side there too.)
-
-### Environment variables
-
-| Variable | Default | Description |
-|---|---|---|
-| `DASHBOARD_PORT` | `4820` | Port the Express server listens on |
-| `CLAUDE_DASHBOARD_PORT` | `4820` | Port the hook handler uses when posting events to the dashboard |
-| `DASHBOARD_DB_PATH` | `data/dashboard.db` | Path to the SQLite database file |
-| `NODE_ENV` | `development` | Set to `production` to serve built client |
-| `DASHBOARD_CLIENT_DIST` | `client/dist` | Directory the built UI is served from in production. Set by the `agenthub` plugin bootstrap to its own runtime dir, because the plugin cache is replaced on every update |
-| `AGENTHUB_IMPORT_MAX_BYTES` | `1073741824` (1 GB) | Maximum size per uploaded file on `/api/import/upload` |
-| `AGENTHUB_IMPORT_MAX_FILES` | `2000` | Maximum number of files per upload request |
-| `AGENTHUB_IMPORT_MAX_EXTRACT_BYTES` | `4294967296` (4 GB) | Maximum uncompressed bytes any single archive is allowed to expand to (zip-bomb defense) |
-
-Example with a custom port:
-
-```bash
-DASHBOARD_PORT=9000 npm run dev
-```
-
-> [!NOTE]
-> You usually do **not** need to set `DASHBOARD_PORT` manually. `npm run dev` is wrapped by `scripts/dev.js`, which probes both `127.0.0.1` and `::1` (so an SSH `LocalForward` bound to one loopback can't slip past) and picks the first free port in `4820–4859` automatically. The chosen port is propagated to the Vite dev proxy via `DASHBOARD_PORT`, and the Express server writes it to `~/.claude/.agenthub.json` so the Claude Code hook handler discovers it without any env var.
->
-> Multiple dashboards can run side by side — for example two `npm run dev` checkouts, or `npm run dev` alongside `npm start`. Each one appends its `{port, pid, startedAt}` entry to the discovery file, and `scripts/hook-handler.js` fan-outs every hook event to every live entry, so both UIs keep their real-time stream.
->
-> Setting `CLAUDE_DASHBOARD_PORT=N` overrides discovery entirely and forces the hook handler to a single port — useful for tests and container setups where the in-process discovery file isn't reachable from the host.
->
-> If you bypass the picker (e.g. `npm run dev:raw`, container builds, or anything else that calls `node server/index.js` directly), make sure your client is built / proxied against the port the server actually bound.
-
-### Agent extension setup (Claude Code + Codex)
-
-This repository ships extension files for both agent ecosystems:
-
-- Claude Code:
-  - `CLAUDE.md`
-  - `.claude/rules/*`
-  - `skills/*` (the `agenthub` plugin's own skills)
-  - `agents/*` (the `agenthub` plugin's own agents)
-- Codex:
-  - `AGENTS.md`
-  - `.codex/config.toml`
-  - `.codex/rules/default.rules`
-  - `.codex/agents/*`
-  - `.codex/skills/*`
-
-See [`.codex/README.md`](./.codex/README.md) for Codex extension details.
-
-### PWA configuration (optional)
-
-The dashboard ships as a Progressive Web App. No configuration is required — its manifest and service worker are included out of the box.
-
-**Customising the manifest:** Edit `client/public/manifest.json`. Common fields to change:
-
-- `name` / `short_name` — displayed on the home screen / dock
-- `theme_color` — address bar / title bar tint (default: `#6366f1`)
-- `background_color` — splash screen background
-- `start_url` — entry point when launched from home screen
-
-**Updating the service worker cache:** The SW has a `CACHE_NAME` constant (e.g. `dashboard-v2`). After deploying new assets, bump the version string to force browsers to re-fetch — though for the dashboard this is rarely needed: hashed `/assets/*` URLs are immutable per build, everything else is fetched network-first with cache fallback, and a `controllerchange` listener in the client reloads the page exactly once when a new SW takes over, so a rebuild propagates without a hard refresh.
-
-**Browser support:** PWA install prompts appear in Chrome 107+, Edge 107+, and Firefox 110+ (desktop and Android). Safari supports `apple-mobile-web-app-capable` for iOS home-screen mode but does not show an install banner.
-
-**Verifying PWA status:** Open DevTools → Application → Manifest to confirm the manifest loads. Check the Service Workers section to verify the SW is registered and active. The Lighthouse PWA audit should pass all core checks.
-
----
-
-## Database
-
-The SQLite database is created automatically at `data/dashboard.db` on first run. The directory is created if it does not exist. The database uses WAL mode for concurrent reads and foreign keys for referential integrity.
-
-### Clear all data
-
-To remove all sessions, agents, events, and token usage (useful after running seed data or for a clean start):
-
-```bash
-npm run clear-data
-```
-
-### Data management via Settings page
-
-The Settings page (`/settings`) provides a UI for the following. **Model Pricing**
-and **Hook Configuration** are not on its Dashboard tab: they sit under the
-Claude Code tab's **Overview** (Settings → Claude Code → Overview), beside
-CLAUDE_HOME; Codex (its Overview) and Antigravity have their own pricing and
-hooks in their own tabs.
-
-- **Model Pricing** — view and edit per-model cost rates, reset to defaults, add custom models
-- **Hook Configuration** — check which hooks are installed and reinstall them
-- **Data Export** — download all sessions, agents, events, and pricing as a JSON file
-- **Session Cleanup** — abandon stale active sessions after N hours, purge old completed sessions after N days
-- **Clear All Data** — remove all sessions, agents, events, and token usage
-- **Data Management** and **About** sections render with loading placeholders while server info is being fetched, so the page is always fully navigable
-
-### Seed demo data
-
-To populate the dashboard with sample sessions, agents, and events for UI exploration:
-
-```bash
-npm run seed
-```
-
----
-
-## Importing existing Claude Code history
-
-The dashboard automatically imports sessions from `~/.claude/projects/` on
-**every startup**, so if Claude Code has been used on this machine, you'll
-see history immediately after the first launch. If you need to bring in
-history from another machine, from a backup, or just force a rescan, use
-**Settings → Import History** in the UI — it's a guided, drag-and-drop
-experience with live progress.
-### Pick the right mode
-
-```mermaid
-flowchart TD
-    Q["Where is the history?"] --> Q1{Is it on this machine<br/>under ~/.claude/projects?}
-    Q1 -->|yes, and I just want<br/>to re-scan| M1["Mode: Rescan default folder<br/>one click"]
-    Q1 -->|yes, but in another folder<br/>on this machine| M2["Mode: Scan a folder<br/>paste the absolute path"]
-    Q1 -->|no — it's on another machine<br/>or in an archive file| M3["Mode: Upload files<br/>drag-drop JSONL or archive"]
-
-    M3 --> PREP["Archive source:<br/>tar -czf claude-history.tar.gz<br/>-C ~/.claude projects"]
-
-    style M1 fill:#10b981,stroke:#34d399,color:#fff
-    style M2 fill:#f59e0b,stroke:#fbbf24,color:#000
-    style M3 fill:#a855f7,stroke:#c084fc,color:#fff
-```
-
-### Step-by-step: moving history from one machine to another
-
-**On the source machine**, bundle the projects folder:
-
-```bash
-# macOS / Linux
-tar -czf claude-history.tar.gz -C ~/.claude projects
-
-# Windows (PowerShell, via built-in tar)
-tar -czf claude-history.tar.gz -C "$env:USERPROFILE\.claude" projects
-```
-
-Transfer the resulting `claude-history.tar.gz` to the destination machine
-however you like — AirDrop, `scp`, USB, cloud storage.
-
-**On the destination machine**, in the dashboard:
-
-1. Open **Settings → Import History**.
-2. Pick **Upload files** (the third tab).
-3. Drag the archive onto the drop zone.
-4. Click **Upload & Import** and watch the progress.
-5. When the green result card appears, open **Analytics → Cost** to confirm
-   per-model token totals and estimated cost.
-
-### Supported inputs
-
-Any of the following can be dropped onto the upload zone or found inside a
-folder given to **Scan a folder**:
-
-- `.jsonl` — session transcripts
-- `.meta.json` — subagent metadata sidecars
-- `.zip` — extracted with path-traversal protection
-- `.tar`, `.tar.gz`, `.tgz` — extracted via the `tar` package
-- `.gz` — single gzipped JSONL (streaming-decompressed)
-
-### Accuracy guarantees
-
-- **Idempotent** — re-importing never double-counts. Sessions are
-  deduplicated by UUID.
-- **Cost-preserving** — the `token_usage` table uses `baseline_*` columns
-  to preserve pre-compaction token totals, so re-ingesting a compacted
-  transcript never erases historical cost.
-- **Same parser as live** — `parseSessionFile` + `importSession` is the
-  single source of truth for both hook-driven ingestion and manual
-  import, so imported numbers match captured numbers exactly.
-
-### Safety
-
-Archive extraction is hardened against path traversal and archive bombs.
-The defaults are generous for real-world transcripts but tight enough to
-stop obvious attacks; see the env vars table above for
-`AGENTHUB_IMPORT_MAX_BYTES`, `AGENTHUB_IMPORT_MAX_FILES`, and
-`AGENTHUB_IMPORT_MAX_EXTRACT_BYTES`.
-
-### CLI alternative
-
-For scripts and automation, the same logic runs from the terminal:
-
-```bash
-# Import (or re-import) everything under ~/.claude/projects
-npm run import-history
-
-# Dry run — show what would be imported without writing
-node scripts/import-history.js --dry-run
-
-# Scope to a single project dir
-node scripts/import-history.js --project my-project
-```
-
----
-
-## Scripts reference
-
-| Script | Command | Description |
-|---|---|---|
-| `setup` | `npm run setup` | Install all dependencies (server + client) |
-| `dev` | `npm run dev` | Start server + client in development mode |
-| `start` | `npm start` | Start server in production mode |
-| `build` | `npm run build` | Build the React client to `client/dist/` |
-| `install-hooks` | `npm run install-hooks` | Write Claude Code hooks to `~/.claude/settings.json` |
-| `clear-data` | `npm run clear-data` | Delete all data from the database |
-| `seed` | `npm run seed` | Insert demo sessions/agents/events |
-| `import-history` | `npm run import-history` | Import legacy sessions from `~/.claude/` (also runs on startup) |
-| `claude` | Claude CLI | Uses `CLAUDE.md`, `.claude/rules`, and `.claude/skills` automatically |
-| `test` | `npm test` | Run all server and client tests |
-| `test:server` | `npm run test:server` | Run server integration tests only |
-| `test:client` | `npm run test:client` | Run client unit tests only |
-| `format` | `npm run format` | Format all files with Prettier |
-| `format:check` | `npm run format:check` | Check formatting without writing |
-
----
-
-## Makefile targets
-
-All npm scripts are mirrored as `make` targets for convenience. Run `make help` to list them:
-
-```bash
-make help
-```
-
-Commonly used targets:
-
-| Make target | Equivalent npm command | Description |
-|---|---|---|
-| `make setup` | `npm run setup` | Install all dependencies (root + client) |
-| `make dev` | `npm run dev` | Start server + client in watch mode |
-| `make build` | `npm run build` | Build the React client for production |
-| `make start` | `npm start` | Start the production server |
-| `make prod` | `npm run build && npm start` | Build then start in one step |
-| `make test` | `npm test` | Run all tests (server + client) |
-| `make test-server` | `npm run test:server` | Run server tests only |
-| `make test-client` | `npm run test:client` | Run client tests only |
-| `make format` | `npm run format` | Format all files with Prettier |
-| `make format-check` | `npm run format:check` | Check formatting without writing |
-| `make seed` | `npm run seed` | Load demo data |
-| `make clear-data` | `npm run clear-data` | Delete all data rows |
-
----
-
-## Troubleshooting
-
-### `better-sqlite3` errors during `npm install` / `npm run setup`
-
-These warnings are **harmless**. `better-sqlite3` is an optional dependency — if it cannot compile, npm skips it and the server falls back to Node.js built-in `node:sqlite` (available on Node 22+).
-
-You do **not** need Python, Visual Studio Build Tools, or any C++ compiler to run this project on Node 22+.
-
-If you are on Node 20 or 21 and `better-sqlite3` prebuilds are not available for your platform (there is no `node:sqlite` fallback below Node 22), you have two options:
-
-1. **Upgrade to Node.js 22+** — the built-in `node:sqlite` fallback requires no native compilation at all
-2. **Install build tools** and run `npm rebuild better-sqlite3`:
-   - **Windows:** install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the C++ workload
-   - **macOS:** `xcode-select --install`
-   - **Linux:** `sudo apt install python3 make g++` (Debian/Ubuntu)
-
-### "SQLite backend not available" error on startup
-
-This means neither `better-sqlite3` nor `node:sqlite` could be loaded. The most common cause is running Node.js < 22 without `better-sqlite3` prebuilds. Upgrade to Node.js 22+ to resolve this.
-
-### Database is locked / busy errors
-
-The SQLite database uses WAL mode with a 5-second busy timeout. If you see lock errors:
-
-- Ensure only one dashboard server instance is running
-- Check for zombie `node server/index.js` processes: `ps aux | grep server/index`
-- Delete `data/dashboard.db-wal` and `data/dashboard.db-shm` if the server was killed uncleanly, then restart
-
----
-
-### The run console won't start a run / the terminal never attaches
-
-Runs are tmux-backed: the server executes the `tmux` binary and has no fallback.
-
-```bash
-tmux -V                                               # missing → sudo apt install tmux
-curl -s http://localhost:4820/api/run/tmux            # {"available":true}
-curl -s "http://localhost:4820/api/run/binary?tool=claude"   # {"found":true,"path":"…"}
-```
-
-`{"available":false}` while your own shell finds tmux means the **server's**
-`PATH` differs from yours — typically a systemd `--user` service, which never
-reads your shell profile. Install tmux system-wide (`/usr/bin/tmux`) and
-re-run `agenthub service uninstall && agenthub service install`. The same
-applies to `claude` / `codex`: a run launches them by name.
-
-Install instructions per OS: [INSTALL.md → Step 0](./INSTALL.md#step-0--system-packages).
-
----
-
-### No sessions appearing after starting Claude Code
-
-**Check 1 — Is the server running?**
-
-```bash
-curl http://localhost:4820/api/health
-# Expected: {"status":"ok","timestamp":"..."}
-```
-
-**Check 2 — Are hooks installed?**
-
-Open `~/.claude/settings.json` and confirm it contains a `hooks` section with entries referencing `hook-handler.js`. If not, run:
-
-```bash
-npm run install-hooks
-```
-
-**Check 3 — Did you start a new Claude Code session after the server started?**
-
-Hooks only apply to sessions started after installation. Restart Claude Code.
-
-**Check 4 — Is Node.js in PATH when Claude Code runs hooks?**
-
-On some systems, the shell environment when Claude Code fires hooks may not include the full PATH. Test with:
-
-```bash
-node --version
-```
-
-If Node.js is not found, use the full path to `node` in the hook command. Edit `scripts/install-hooks.js`, replace `node` with the absolute path (e.g. `/usr/local/bin/node`), and re-run `npm run install-hooks`.
-
----
-
-### Dashboard shows "Disconnected" in the sidebar
-
-The WebSocket connection to the server failed. Ensure the server is running:
-
-```bash
-npm run dev
-```
-
-The client will automatically reconnect every 2 seconds once the server is available.
-
----
-
-### Events Today shows 0 despite recent activity
-
-This was a known timezone bug (fixed in current version). If you are still seeing this, ensure you are running the latest code and restart the server.
-
----
-
-### Port 4820 already in use
-
-```bash
-DASHBOARD_PORT=4821 npm run dev
-```
-
-Then update the Vite proxy in `client/vite.config.ts`:
-
-```ts
-proxy: {
-  "/api": "http://localhost:4821",
-  "/ws":  { target: "ws://localhost:4821", ws: true }
-}
-```
-
-And make sure Claude Code posts hooks to the new port:
-
-```bash
-CLAUDE_DASHBOARD_PORT=4821 claude
-# or edit scripts/hook-handler.js and change the default port
-```
+This guide has moved into **[INSTALL.md](./INSTALL.md)** — the one install and
+setup guide (it and this file had grown into near-duplicates). Everything that
+was here is there:
+
+| Was in SETUP.md | Now in INSTALL.md |
+|---|---|
+| How it works | [How it works](./INSTALL.md#how-it-works) |
+| Hook auto-installation, environment variables, agent extensions, PWA | [Configuration](./INSTALL.md#configuration) |
+| Database (clear, Settings page, seed) | [Database](./INSTALL.md#database) |
+| Importing existing Claude Code history | [Step 5](./INSTALL.md#step-5--optional-importing-existing-claude-code-history) |
+| Scripts reference, Makefile targets | [Scripts reference](./INSTALL.md#scripts-reference) |
+| Troubleshooting (incl. "Port 4820 already in use") | [Troubleshooting](./INSTALL.md#troubleshooting) |

bin/agenthub.js

@@ -1284,12 +1284,14 @@ async function cmdDoctor() {
   // warning, not a failure: it costs the run console and `lanes shell`, nothing
   // else.
   try {
-    const { available } = await get("/api/run/tmux");
+    const { available, upgrade } = await get("/api/run/tmux");
     console.log(
-      available
-        ? `${c.green("✔")}  tmux  available to the server`
-        : `${c.yellow("!")}  tmux  not on the server's PATH — Start Run and \`agenthub workspace shell\` will fail. ` +
+      !available
+        ? `${c.yellow("!")}  tmux  not on the server's PATH — Start Run and \`agenthub workspace shell\` will fail. ` +
             `Install it (sudo apt install tmux / brew install tmux), then restart the server`
+        : upgrade
+          ? `${c.yellow("!")}  tmux  ${upgrade}`
+          : `${c.green("✔")}  tmux  available to the server`
     );
   } catch {
     console.log(`${c.dim("·")}  tmux  not reported by this server`);
@@ -2853,8 +2855,8 @@ const COMMAND_GROUPS = [
       ],
       [
         "accounts",
-        "list|add|remove [name]",
-        "Claude account pool: new sessions spread over these 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)"],
     ],
@@ -3932,26 +3934,95 @@ async function cmdServer(sub, flags) {
     } else {
       console.log(c.dim("  an admin already exists — add more with `agenthub users add`"));
     }
+    const wasServer = auth.isServerMode();
     settingsEnv.writeSetting("AGENTHUB_MODE", "server");
     envNote("AGENTHUB_MODE");
     console.log(`${c.green("✔")} server mode on (${file})`);
+    // One Linux user per account (S3) is the default on Linux: install it now
+    // (one sudo), unless it is already in place or `--no-system` opts out.
+    const linux = require(path.join(REPO_ROOT, "server", "lib", "linux-accounts.js"));
+    const shared = flags["no-system"] === true || process.platform !== "linux";
+    if (!shared) {
+      if (linux.serverConf()) {
+        console.log(c.dim("  one Linux user per account is already installed"));
+        // The system unit serves; it reads the mode only when it starts.
+        if (!wasServer) {
+          const r = spawnSync("sudo", [
+            "-n",
+            "systemctl",
+            "restart",
+            "--no-block",
+            "agenthub.service",
+          ]);
+          console.log(
+            r.status === 0
+              ? `${c.green("✔")} agenthub.service restarted`
+              : c.yellow("! restart it: sudo systemctl restart agenthub")
+          );
+        }
+      } else {
+        console.log("  Installing one Linux user per account (asks for your sudo password)…");
+        try {
+          await installSystem({}, settingsEnv);
+        } catch (e) {
+          throw new Error(
+            `${e.message}\n  Server mode is on, but every pane still runs as this account.` +
+              "\n  Fix it and run `agenthub server install-system`, or keep one shared" +
+              " account with `agenthub server setup --no-system`."
+          );
+        }
+      }
+      // The admin made above (and anyone made before) gets their Linux account.
+      process.env.AGENTHUB_MODE = "server";
+      await cmdUsers("provision", [], { all: true });
+    }
     console.log("  Next:");
     console.log(
-      "  1. Restart the dashboard: systemctl --user restart agenthub  (or agenthub start)"
+      shared
+        ? "  1. Restart the dashboard: systemctl --user restart agenthub  (or agenthub start)"
+        : "  1. Log out and back in once, so your shell joins the agenthub groups"
     );
     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)."));
+    if (shared) {
+      console.log(
+        c.yellow(
+          process.platform === "linux"
+            ? "! --no-system: every pane runs as this one Linux account"
+            : "! one Linux user per account needs Linux: every pane runs as this one account"
+        )
+      );
+      console.log(
+        c.dim("  Members see only their own workspaces, but an agent in a pane can read")
+      );
+      console.log(
+        c.dim("  every user's files — 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");
@@ -3969,11 +4040,120 @@ async function cmdServer(sub, flags) {
     return;
   }
   console.error(
-    c.red("✖ Usage: agenthub server setup [--hostname name] [--admin name] | off | status")
+    c.red(
+      "✖ Usage: agenthub server setup [--hostname name] [--admin name] [--no-system] | 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();
@@ -4026,6 +4206,37 @@ async function cmdUsers(sub, positional, flags) {
       );
       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();
@@ -4035,21 +4246,77 @@ async function cmdUsers(sub, positional, flags) {
     default:
       console.error(
         c.red(
-          "✖ Usage: agenthub users list | add <name> [--role admin|analyst|developer] | passwd <name> | role <name> <role> | disable <name> | enable <name> | assign <workspace id> <name> | audit [--limit N]"
+          "✖ 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", "tok 5h", "tok 7d", "quota", "state"],
+    pool
+      .poolStatus()
+      .map((a) => [
+        a.name,
+        a.kind,
+        a.livePanes,
+        a.spend5h.toFixed(2),
+        a.spend7d.toFixed(2),
+        a.tokens5h,
+        a.tokens7d,
+        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) {
+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>`);
+    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.")
@@ -4070,7 +4337,7 @@ async function cmdAccounts(sub, positional) {
     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"],
+      ["account", "live", "$ 5h", "$ 7d", "tok 5h", "tok 7d", "quota 5h", "quota wk", "state"],
       pool
         .poolStatus()
         .map((a) => [
@@ -4078,6 +4345,8 @@ async function cmdAccounts(sub, positional) {
           a.livePanes,
           a.spend5h.toFixed(2),
           a.spend7d.toFixed(2),
+          a.tokens5h,
+          a.tokens7d,
           pct(a.quota?.fiveHour),
           pct(a.quota?.sevenDay),
           a.expired
@@ -4089,9 +4358,13 @@ async function cmdAccounts(sub, positional) {
                 : "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>"));
+  console.error(
+    c.red("✖ Usage: agenthub accounts list | add <name> | remove <name> [--tool codex]")
+  );
   process.exitCode = 1;
 }
 
@@ -4121,7 +4394,7 @@ async function runCommand(argv) {
     case "users":
       return cmdUsers(positional[0], positional.slice(1), flags);
     case "accounts":
-      return cmdAccounts(positional[0], positional.slice(1));
+      return cmdAccounts(positional[0], positional.slice(1), flags);
     case "stats":
       return cmdStats();
     case "kanban":

client/README.md

@@ -52,7 +52,7 @@ 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. 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
+- **Tailwind CSS 3.4** - Utility-first CSS framework; colors are CSS-variable-backed tokens (`darkMode: "class"`) so a Dark/Light/System switch (Settings → Appearance; `useTheme` hook — the sidebar has no theme or language controls, the language lives in Settings → Appearance) re-themes the whole app by flipping one class. A **named theme** per mode is one more attribute: `data-theme` on `<html>` (absent for `default`) selects a CSS-variable block in `index.css` — `.dark[data-theme="darcula|apple-dark|orca-dark"]` and `[data-mode="light"][data-theme="apple-light|intellij-light|canvas|orca-light"]` — that overrides only the tokens it changes. `--tint-base` is `var(--surface-3)` and light `--syn-plain` is `var(--fg-primary)`, so a theme never restates them. A new theme is a block there plus an id in `THEMES` (`hooks/useTheme.ts`) and a label in `components/settings/AppearanceSettings.tsx`; its Settings preview needs no hex, because the swatch re-scopes the same variables on its own element. Storage: `theme` = `dark|light|system`, `agenthub.theme.dark` / `agenthub.theme.light` = theme ids (unknown ⇒ `default`); state is read through `useSyncExternalStore`, never cached in the module, so every consumer and every tab agree. An inline `<script>` at the top of `client/index.html` applies the same keys before first paint (no flash of the stock dark palette); it does not validate ids — the hook does, on mount. The workspace terminal's font is the same kind of preference: `agenthub.terminal.font` = `jetbrains|maple|system` (`lib/terminalFont.ts`, default `jetbrains`) and `agenthub.terminal.fontSize` = 11|12|13|14|15|16|18|20 px (`lib/fontSize.ts`, default 13), picked in Settings → Appearance; a change fires `agenthub-font-size` on `window`, so an open terminal re-fits at once. Settings → Appearance → **Text size** (`#text-size`) sets `agenthub.ui.fontSize` = 14|16|17|18 (Small/Default/Large/Larger), the ROOT font size in px (`lib/fontSize.ts`; the index.html script applies it before first paint too); Tailwind's sizes are rem and `index.css` re-states every `text-[Npx]` class in rem, so all text scales with it. All of these keys are synced to the account like the theme (`PREF_KEYS` in `lib/userPrefs.ts` and `server/routes/me.js`)
 
   **The surface ramp means elevation, and it runs the same direction in both themes: a higher index is LIGHTER in dark and LIGHTER in light.** So in light mode the page is the *darkest* step (`surface-0`, `#eceef2`) and a `.card` is brighter than the page it sits on (`surface-3`, `#fdfdfe`), which is also what makes every `hover:bg-surface-N` lift rather than dim. Light mode originally used Radix slate in its native direction — index up meant darker — which inverted the whole language: a near-white page (the glare complaint) under grey cards that read as recessed. Never "fix" a light-mode colour by swapping which step a component uses; fix the value of the step.
 

client/index.html

@@ -2,7 +2,8 @@
 <html lang="en" class="dark">
   <head>
     <!-- Apply the saved appearance before first paint (same keys as
-         src/hooks/useTheme.ts, which re-applies and validates on mount). -->
+         src/hooks/useTheme.ts, which re-applies and validates on mount, and
+         src/lib/fontSize.ts). -->
     <script>
       try {
         var m = localStorage.getItem("theme");
@@ -17,6 +18,9 @@
         r.classList.toggle("dark", d);
         r.setAttribute("data-mode", d ? "dark" : "light");
         if (t && t !== "default") r.setAttribute("data-theme", t);
+        // Text size (src/lib/fontSize.ts, UI_FONT_SIZES): the root font size.
+        var f = Number(localStorage.getItem("agenthub.ui.fontSize"));
+        if (f === 14 || f === 17 || f === 18) r.style.fontSize = f + "px";
       } catch (e) {}
     </script>
     <meta charset="UTF-8" />
@@ -30,7 +34,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 +49,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 +74,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-lock.json

@@ -1204,9 +1204,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1362,9 +1359,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1379,9 +1373,6 @@
         "arm"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1396,9 +1387,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1413,9 +1401,6 @@
         "arm64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1430,9 +1415,6 @@
         "loong64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1447,9 +1429,6 @@
         "loong64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1464,9 +1443,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1481,9 +1457,6 @@
         "ppc64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1498,9 +1471,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1515,9 +1485,6 @@
         "riscv64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1532,9 +1499,6 @@
         "s390x"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1549,9 +1513,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "glibc"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [
@@ -1566,9 +1527,6 @@
         "x64"
       ],
       "dev": true,
-      "libc": [
-        "musl"
-      ],
       "license": "MIT",
       "optional": true,
       "os": [

client/src/App.tsx

@@ -64,6 +64,7 @@ import { GlobalTooltip } from "./components/Tooltip";
 import { Toaster } from "./components/Toaster";
 import { ConfirmHost } from "./components/ConfirmHost";
 import { RouteErrorBoundary, reloadOnce } from "./components/RouteErrorBoundary";
+import { usePermissions } from "./components/AuthGate";
 import { NotFound } from "./pages/NotFound";
 import { useWebSocket } from "./hooks/useWebSocket";
 import { useNotifications } from "./hooks/useNotifications";
@@ -87,7 +88,11 @@ const SessionDetail = lazy(() =>
 const SnapshotView = lazy(() =>
   import("./pages/SnapshotView").then((m) => ({ default: m.SnapshotView }))
 );
-const Users = lazy(() => import("./pages/Users").then((m) => ({ default: m.Users })));
+const FilesPage = lazy(() => import("./pages/FilesPage").then((m) => ({ default: m.FilesPage })));
+const Administration = lazy(() =>
+  import("./pages/Administration").then((m) => ({ default: m.Administration }))
+);
+const Artifacts = lazy(() => import("./pages/Artifacts").then((m) => ({ default: m.Artifacts })));
 
 function PageFallback() {
   const { t } = useTranslation();
@@ -107,6 +112,11 @@ function Page({ children }: { children: ReactNode }) {
   );
 }
 
+/** A page only a shared server needs (the File Explorer): local mode goes home. */
+function ServerOnly({ children }: { children: ReactNode }) {
+  return usePermissions().local ? <Navigate to="/" replace /> : <>{children}</>;
+}
+
 /** Keyed by the id so moving to another session starts from fresh state. */
 function SessionDetailRoute() {
   const { id } = useParams();
@@ -211,13 +221,33 @@ export default function App() {
               }
             />
             <Route
-              path="users"
+              path="artifacts"
               element={
                 <Page>
-                  <Users />
+                  <Artifacts />
                 </Page>
               }
             />
+            <Route
+              path="files"
+              element={
+                <ServerOnly>
+                  <Page>
+                    <FilesPage />
+                  </Page>
+                </ServerOnly>
+              }
+            />
+            <Route
+              path="admin"
+              element={
+                <Page>
+                  <Administration />
+                </Page>
+              }
+            />
+            {/* The Users page became Administration's first tab. */}
+            <Route path="users" element={<Navigate to="/admin" replace />} />
             <Route
               path="settings/*"
               element={

client/src/components/AuthGate.tsx

@@ -6,25 +6,43 @@
  * 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`;
+ * previous user's data. `useAuth()` gives the sidebar the user, `logout`, and
+ * `updateUser` (Settings → Account's saved display name shows at once);
  * `usePermissions()` says what that user's role may do, so pages hide the rest.
+ * Once an account is known (local mode is one), its own UI preferences are
+ * loaded into this browser (`lib/userPrefs.ts`).
+ * The login page follows the OS's light/dark (`applySystemTheme`).
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
 import {
   createContext,
+  useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useState,
   type FormEvent,
   type ReactNode,
 } from "react";
 import { useTranslation } from "react-i18next";
+import { Eye, EyeOff } from "lucide-react";
+import { BRAND_LOGO } from "../lib/brand";
+import { applySystemTheme } from "../hooks/useTheme";
 import { api, AUTH_REQUIRED_EVENT, type AuthState, type AuthUser } from "../lib/api";
+import { hydrate } from "../lib/userPrefs";
 
-type AuthValue = { state: AuthState; logout: () => Promise<void> };
+type AuthValue = {
+  state: AuthState;
+  logout: () => Promise<void>;
+  updateUser: (patch: Partial<AuthUser>) => void;
+};
 
-const AuthContext = createContext<AuthValue>({ state: { mode: "local" }, logout: async () => {} });
+const AuthContext = createContext<AuthValue>({
+  state: { mode: "local" },
+  logout: async () => {},
+  updateUser: () => {},
+});
 
 /** The current login; `{mode: "local"}` outside server mode (and in tests). */
 export const useAuth = () => useContext(AuthContext);
@@ -45,6 +63,10 @@ export function usePermissions() {
   const isAdmin = local || user?.role === "admin";
   return {
     isAdmin,
+    // Local mode: one person on their own machine — what only serves a
+    // shared server (File Explorer, uploads, AgentHub's own git logins) is
+    // hidden; their desktop and their own git config already do it.
+    local,
     seesAll: local || (!!user && user.role !== "developer"),
     // A developer only ever sees their own rows, so everything shown is theirs.
     canEditLane: (lane?: { owner_id?: number | null } | null) =>
@@ -114,6 +136,27 @@ export function AuthGate({ children }: { children: ReactNode }) {
     };
   }, []);
 
+  // The signed-in account's own preferences (lib/userPrefs.ts): loaded once
+  // per account, so a second login in this browser brings that account's.
+  const account =
+    state?.mode === "local"
+      ? "local"
+      : state?.mode === "server" && state.user
+        ? `u${state.user.id}`
+        : null;
+  useEffect(() => {
+    if (account) void hydrate();
+  }, [account]);
+
+  // Stable, so a page may list it as an effect dependency.
+  const updateUser = useCallback(
+    (patch: Partial<AuthUser>) =>
+      setState((s) =>
+        s && s.mode === "server" && s.user ? { ...s, user: { ...s.user, ...patch } } : s
+      ),
+    []
+  );
+
   if (!state) return null;
   if (state.mode === "server" && !state.user) {
     return <LoginPage onLoggedIn={(user) => setState({ mode: "server", user })} />;
@@ -122,16 +165,27 @@ export function AuthGate({ children }: { children: ReactNode }) {
     await api.auth.logout().catch(() => {});
     setState({ mode: "server", user: null });
   };
-  return <AuthContext.Provider value={{ state, logout }}>{children}</AuthContext.Provider>;
+  return (
+    <AuthContext.Provider value={{ state, logout, updateUser }}>{children}</AuthContext.Provider>
+  );
 }
 
 function LoginPage({ onLoggedIn }: { onLoggedIn: (user: AuthUser) => void }) {
   const { t } = useTranslation();
   const [username, setUsername] = useState("");
   const [password, setPassword] = useState("");
+  const [showPassword, setShowPassword] = useState(false);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
+  // Nobody is signed in, so no account's theme applies: follow the OS, live.
+  useLayoutEffect(() => {
+    applySystemTheme();
+    const mq = window.matchMedia?.("(prefers-color-scheme: dark)");
+    mq?.addEventListener?.("change", applySystemTheme);
+    return () => mq?.removeEventListener?.("change", applySystemTheme);
+  }, []);
+
   const submit = async (e: FormEvent) => {
     e.preventDefault();
     setBusy(true);
@@ -149,38 +203,83 @@ function LoginPage({ onLoggedIn }: { onLoggedIn: (user: AuthUser) => void }) {
 
   return (
     <main className="flex min-h-screen items-center justify-center bg-surface-0 p-4">
-      <form onSubmit={submit} className="card w-full max-w-sm space-y-4 p-6">
-        <h1 className="text-lg font-semibold text-fg-primary">{t("auth.title")}</h1>
-        <label className="block space-y-1 text-sm text-fg-secondary">
-          <span>{t("auth.username")}</span>
-          <input
-            className="input w-full"
-            autoComplete="username"
-            autoFocus
-            required
-            value={username}
-            onChange={(e) => setUsername(e.target.value)}
-          />
-        </label>
-        <label className="block space-y-1 text-sm text-fg-secondary">
-          <span>{t("auth.password")}</span>
-          <input
-            className="input w-full"
-            type="password"
-            autoComplete="current-password"
-            required
-            value={password}
-            onChange={(e) => setPassword(e.target.value)}
-          />
-        </label>
-        {error && (
-          <p role="alert" className="text-sm text-status-danger">
-            {error}
-          </p>
-        )}
-        <button type="submit" className="btn-primary w-full" disabled={busy}>
-          {busy ? t("auth.submitting") : t("auth.submit")}
-        </button>
+      <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/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

@@ -51,6 +51,7 @@
  * ## Internal dependencies
  * - `./Sidebar`
  * - `./UpdateNotifier`
+ * - `./lanes/InterruptedSessionsPrompt` (the "resume interrupted sessions?" dialog)
  * - `./Sagi/SagiMount`
  *
  * ## Public surface
@@ -75,14 +76,23 @@
  *
  * ----------------------------------------------------------------------------- */
 
-import { useState, useCallback, useEffect, useSyncExternalStore } from "react";
+import { lazy, Suspense, useState, useCallback, useEffect, useSyncExternalStore } from "react";
 import { Outlet, useLocation } from "react-router-dom";
 import { Menu } from "lucide-react";
 import { useTranslation } from "react-i18next";
 import { Sidebar, SIDEBAR_STORAGE_KEY, loadCollapsed } from "./Sidebar";
 import { UpdateNotifier } from "./UpdateNotifier";
+import { InterruptedSessionsPrompt } from "./lanes/InterruptedSessionsPrompt";
 import { SagiMount } from "./Sagi/SagiMount";
 import { StatusBar } from "./StatusBar";
+import { useOnboarding } from "../lib/userPrefs";
+import { OnboardingTour } from "./onboarding/OnboardingTour";
+
+// Loaded only for an account that has not finished onboarding: the wizard
+// carries the appearance, pet and notification settings screens.
+const OnboardingWizard = lazy(() =>
+  import("./onboarding/OnboardingWizard").then((m) => ({ default: m.OnboardingWizard }))
+);
 
 const WIDTH_KEY = "agenthub.sidebar.width";
 /** The default width, and the narrowest the edge drags to. */
@@ -132,6 +142,7 @@ export function Layout({ wsConnected }: LayoutProps) {
   const { t } = useTranslation("nav");
   const [collapsed, setCollapsed] = useState(loadCollapsed);
   const [connectionOpen, setConnectionOpen] = useState(false);
+  const onboarding = useOnboarding();
   const [updateAvailable, setUpdateAvailable] = useState(false);
   const drawer = useMedia(DRAWER_QUERY);
   const [drawerOpen, setDrawerOpen] = useState(false);
@@ -171,7 +182,14 @@ export function Layout({ wsConnected }: LayoutProps) {
         {t("skipToContent")}
       </a>
       <UpdateNotifier />
+      <InterruptedSessionsPrompt />
       <SagiMount />
+      {onboarding.loaded && !onboarding.onboardedAt && (
+        <Suspense fallback={null}>
+          <OnboardingWizard />
+        </Suspense>
+      )}
+      <OnboardingTour />
       {drawer && drawerOpen && (
         <div
           aria-hidden

client/src/components/PathPickButton.tsx

@@ -6,9 +6,9 @@
  * user chose. A browser's picker cannot give a page that path, so the dialog
  * opens on the server's desktop — which is only this user's screen when the
  * browser runs on the same machine. Anywhere else (a LAN browser, a server
- * with no desktop or no zenity/kdialog) a folder falls back to the in-app
- * `FolderBrowseModal` (as it does on any other failure), and a file to typing
- * the path.
+ * with no desktop or no zenity/kdialog) it falls back to the in-app
+ * `FolderBrowseModal` (as it does on any other failure) — for a file field
+ * too, which then lists files and picks one on click.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
@@ -16,12 +16,8 @@ import { useState } from "react";
 import { useTranslation } from "react-i18next";
 import { FolderOpen } from "lucide-react";
 import { api } from "../lib/api";
-import { toast } from "../lib/toast";
 import { FolderBrowseModal } from "./lanes/FolderBrowseModal";
 
-/** Server answers that mean "no native picker for this browser" — not a fault. */
-const FALLBACK = new Set(["EREMOTE", "EBADORIGIN", "ENODIALOG"]);
-
 export function PathPickButton({
   kind = "dir",
   start,
@@ -44,15 +40,10 @@ export function PathPickButton({
     try {
       const r = await api.lanes.pickPath(kind, start?.trim() || undefined);
       if (r.path) onPick(r.path);
-    } catch (err) {
-      const code = (err as { code?: string }).code;
-      // A folder always has the in-app browser to fall back on, whatever went
-      // wrong with the native one (a crashed dialog, one already open).
-      if (kind === "dir") setFallback(true);
-      else if (code && FALLBACK.has(code)) toast.info(t("browse.typePath"));
-      else {
-        toast.error(err instanceof Error ? err.message : String(err));
-      }
+    } catch {
+      // The in-app browser is the fallback whatever went wrong with the
+      // native one: a LAN browser (EREMOTE), no desktop, a crashed dialog.
+      setFallback(true);
     } finally {
       setBusy(false);
     }
@@ -76,6 +67,7 @@ export function PathPickButton({
       <div className="contents" onClick={(e) => e.stopPropagation()}>
         <FolderBrowseModal
           open={fallback}
+          kind={kind}
           initialPath={start?.trim() || undefined}
           onSelect={onPick}
           onClose={() => setFallback(false)}

client/src/components/Sagi/PetChat.tsx

@@ -0,0 +1,591 @@
+/**
+ * @file PetChat.tsx
+ * @description The pet's chat window — its whole UI: clicking the pet opens
+ * it. Above the conversation sits what the pet knows (`info`: live / waiting /
+ * errored, the sessions that need you, Mute, Clear alerts — `SagiInfo.tsx`).
+ * Before a chat runs, a question the pet can answer itself (`onLocal`: status,
+ * who are you…) is answered right here; anything else — and every message once
+ * a chat runs — goes to the AI: the first message starts a
+ * session of the user's DEFAULT AI tool (`agenthub.defaultTool`, Claude or
+ * Codex — the two with a readable transcript) in the "Sagi" workspace, in its
+ * first free tab (`startInFreeTabDetailed`), and the conversation is shown as
+ * chat bubbles read from the session's transcript. Follow-ups are typed into
+ * that session's pane through a terminal attached OFF-SCREEN (`TerminalView`
+ * in a fixed box left of the viewport — `submitToRun` needs a mounted,
+ * attached pane, exactly like the workspace's own Chat view), so nothing new
+ * reaches the server. A menu the CLI asks with (a permission or trust prompt)
+ * is read off that pane and answered with `PaneMenuCard`. The chat is kept in
+ * `localStorage` (`agenthub.pet.chat`) while its pane lives, so closing and
+ * reopening the window continues it; **New chat** STOPS that session (kills
+ * its pane and archives it, asking first only mid-reply), **Open in workspace**
+ * opens its pane there. Opening never resumes an ended session: once the pane
+ * is gone, the next message starts a new one.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useCallback, useEffect, useRef, useState, type FormEvent, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { ArrowUp, ExternalLink, Loader2, SquarePen, Wrench, X } from "lucide-react";
+import { api } from "../../lib/api";
+import type { TranscriptMessage } from "../../lib/types";
+import { readDefaultMode, readDefaultTool } from "../../lib/sessionDefaults";
+import {
+  answerRunMenu,
+  chooseRunOption,
+  interruptRun,
+  readRunMenu,
+  submitToRun,
+  type PaneMenu,
+} from "../../lib/panePaste";
+import { isSubmitEnter } from "../../lib/keys";
+import { confirmDialog } from "../../lib/confirm";
+import { toast } from "../../lib/toast";
+import { startInFreeTabDetailed } from "../lanes/startSession";
+import { TerminalView } from "../run/TerminalView";
+import { PaneMenuCard } from "../run/PaneChat";
+import { MarkdownContent } from "../conversation/MarkdownContent";
+
+/** Tools whose session the chat can read back (a transcript AgentHub parses). */
+export const PET_CHAT_TOOLS = new Set(["claude", "codex"]);
+const CHAT_KEY = "agenthub.pet.chat";
+const POLL_MS = 1500;
+const MENU_POLL_MS = 700;
+// A follow-up waits this long for the off-screen pane to attach.
+const SEND_TRIES = 20;
+const SEND_RETRY_MS = 250;
+
+/** The session the chat is talking to. */
+export interface PetChatRef {
+  laneId: number;
+  runId: string;
+  tool: string;
+}
+
+export function readPetChat(): PetChatRef | null {
+  try {
+    const v = JSON.parse(localStorage.getItem(CHAT_KEY) ?? "null") as Partial<PetChatRef> | null;
+    if (
+      v &&
+      typeof v.laneId === "number" &&
+      typeof v.runId === "string" &&
+      typeof v.tool === "string"
+    )
+      return { laneId: v.laneId, runId: v.runId, tool: v.tool };
+  } catch {
+    /* unreadable: no chat */
+  }
+  return null;
+}
+
+function writePetChat(ref: PetChatRef | null) {
+  try {
+    if (ref) localStorage.setItem(CHAT_KEY, JSON.stringify(ref));
+    else localStorage.removeItem(CHAT_KEY);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** The tool a new chat starts: the user's default, when the chat can show it. */
+export function petChatTool(): string | null {
+  const tool = readDefaultTool() ?? "claude";
+  return PET_CHAT_TOOLS.has(tool) ? tool : null;
+}
+
+type Line =
+  | { key: string; role: "user" | "assistant"; text: string }
+  | { key: string; role: "tools"; names: string[] };
+
+/** A human line's text: Claude Code's own injected lines (`<command-…>`,
+ *  `<system-reminder>`…) are not something the user said. */
+const humanText = (m: TranscriptMessage) =>
+  m.content
+    .filter((c) => c.type === "text" && c.text)
+    .map((c) => c.text!.trim())
+    .filter((t) => t && !t.startsWith("<"))
+    .join("\n\n");
+
+/** The transcript as chat lines: the user's words, the assistant's prose, and
+ *  each run of tool calls between them folded into one chip. */
+export function chatLines(messages: TranscriptMessage[]): Line[] {
+  const out: Line[] = [];
+  messages.forEach((m, i) => {
+    const sender = m.sender ?? m.type;
+    if (sender === "user") {
+      const text = humanText(m);
+      if (text) out.push({ key: `u${i}`, role: "user", text });
+      return;
+    }
+    if (m.type !== "assistant") return;
+    m.content.forEach((c, j) => {
+      if (c.type === "text" && c.text?.trim()) {
+        out.push({ key: `a${i}-${j}`, role: "assistant", text: c.text.trim() });
+      } else if (c.type === "tool_use" && c.name) {
+        const last = out[out.length - 1];
+        if (last?.role === "tools") last.names.push(c.name);
+        else out.push({ key: `t${i}-${j}`, role: "tools", names: [c.name] });
+      }
+    });
+  });
+  return out;
+}
+
+/** Still working: the last line is the user's, or an assistant turn not ended. */
+function isBusy(messages: TranscriptMessage[]): boolean {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]!;
+    const sender = m.sender ?? m.type;
+    if (m.type === "assistant") return m.stop_reason !== undefined && m.stop_reason !== "end_turn";
+    if (sender === "user" && humanText(m)) return true;
+  }
+  return false;
+}
+
+/** "Read ×2 · Bash" */
+function toolSummary(names: string[]): string {
+  const counts = new Map<string, number>();
+  names.forEach((n) => counts.set(n, (counts.get(n) ?? 0) + 1));
+  return [...counts].map(([n, c]) => (c > 1 ? `${n} ×${c}` : n)).join(" · ");
+}
+
+/** What the container made of a message: an answer the pet gives itself, or
+ *  `handled` (it took the message elsewhere); null sends it to the AI. */
+export type PetLocalReply = { answer: string } | { handled: true } | null;
+
+interface PetChatProps {
+  /** The pet's shown name, for the header and greeting. */
+  name: string;
+  /** Shown in place of the plain name (the rename button). */
+  title?: ReactNode;
+  /** Extra header buttons, before Open in workspace (the pat heart). */
+  headerActions?: ReactNode;
+  /** Under the header: what the pet knows (status, sessions that need you). */
+  info?: ReactNode;
+  /** Asked first while no chat runs. */
+  onLocal?: (text: string) => PetLocalReply;
+  onClose: () => void;
+  /** Opens the chat's pane in its workspace. */
+  onOpenWorkspace: (laneId: number, runId: string) => void;
+  /** The thinking mood while a reply is being written. */
+  onBusy?: (busy: boolean) => void;
+}
+
+export function PetChat({
+  name,
+  title,
+  headerActions,
+  info,
+  onLocal,
+  onClose,
+  onOpenWorkspace,
+  onBusy,
+}: PetChatProps) {
+  const { t } = useTranslation("settings");
+  const [chat, setChat] = useState<PetChatRef | null>(readPetChat);
+  const [sessionId, setSessionId] = useState<string | null>(null);
+  const [messages, setMessages] = useState<TranscriptMessage[]>([]);
+  // Sent but not in the transcript yet.
+  const [pending, setPending] = useState<string | null>(null);
+  const [starting, setStarting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [draft, setDraft] = useState("");
+  const [menu, setMenu] = useState<PaneMenu | null>(null);
+  // The pet's own answers, given before any chat ran.
+  const [local, setLocal] = useState<Line[]>([]);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  const remember = (ref: PetChatRef | null) => {
+    writePetChat(ref);
+    setChat(ref);
+    setSessionId(null);
+    setMessages([]);
+    setMenu(null);
+  };
+
+  // A remembered chat whose pane is gone is over: forget it, the next message starts anew.
+  useEffect(() => {
+    if (!chat) return;
+    let live = true;
+    const check = () =>
+      api.run
+        .get(chat.runId)
+        .then((h) => {
+          if (!live) return;
+          if (h.status !== "running") remember(null);
+          else if (h.sessionId) setSessionId(h.sessionId);
+        })
+        .catch(() => live && remember(null));
+    void check();
+    // Codex learns its session only after a while; Claude's is known at start.
+    const timer = window.setInterval(() => {
+      if (!sessionId) void check();
+    }, POLL_MS);
+    return () => {
+      live = false;
+      window.clearInterval(timer);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chat?.runId, sessionId]);
+
+  // The conversation, polled while the window is open.
+  useEffect(() => {
+    if (!sessionId) return;
+    let live = true;
+    const load = () =>
+      api.sessions
+        .transcript(sessionId, { limit: 60 })
+        .then((r) => {
+          if (!live) return;
+          setMessages((prev) =>
+            prev.length === r.messages.length &&
+            JSON.stringify(prev[prev.length - 1]) ===
+              JSON.stringify(r.messages[r.messages.length - 1])
+              ? prev
+              : r.messages
+          );
+        })
+        .catch(() => undefined); // not started yet: the next poll asks again
+    void load();
+    const timer = window.setInterval(load, POLL_MS);
+    return () => {
+      live = false;
+      window.clearInterval(timer);
+    };
+  }, [sessionId]);
+
+  // A menu the CLI shows in the pane (permission, trust, a question).
+  useEffect(() => {
+    if (!chat) return;
+    const read = () =>
+      setMenu((prev) => {
+        const next = readRunMenu(chat.runId);
+        return JSON.stringify(next) === JSON.stringify(prev) ? prev : next;
+      });
+    const timer = window.setInterval(read, MENU_POLL_MS);
+    return () => window.clearInterval(timer);
+  }, [chat]);
+
+  const lines = [...local, ...chatLines(messages)];
+  // The pending line shows until the transcript has it.
+  useEffect(() => {
+    if (pending && lines.some((l) => l.role === "user" && l.text === pending.trim()))
+      setPending(null);
+  }, [lines, pending]);
+  const busy = starting || !!pending || isBusy(messages);
+  useEffect(() => onBusy?.(busy), [busy, onBusy]);
+  useEffect(() => () => onBusy?.(false), [onBusy]);
+
+  // Keep the newest in sight.
+  useEffect(() => {
+    const el = listRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }, [lines.length, pending, busy, menu]);
+
+  const send = useCallback(
+    async (text: string) => {
+      const prompt = text.trim();
+      if (!prompt || starting) return;
+      setError(null);
+      if (!chat && onLocal) {
+        const reply = onLocal(prompt);
+        if (reply && "handled" in reply) return;
+        if (reply) {
+          const n = Date.now();
+          setLocal((prev) => [
+            ...prev,
+            { key: `lu${n}`, role: "user", text: prompt },
+            { key: `la${n}`, role: "assistant", text: reply.answer },
+          ]);
+          return;
+        }
+      }
+      setPending(prompt);
+      if (chat) {
+        // Typed into the attached pane; it may still be attaching.
+        for (let i = 0; i < SEND_TRIES; i++) {
+          if (submitToRun(chat.runId, prompt)) return;
+          await new Promise((r) => setTimeout(r, SEND_RETRY_MS));
+        }
+        setPending(null);
+        setDraft(prompt);
+        setError(t("sagi.chat.notSent"));
+        return;
+      }
+      const tool = petChatTool() ?? "claude";
+      setStarting(true);
+      try {
+        const { lane } = await api.lanes.ensure({ title: "Sagi" });
+        const r = await startInFreeTabDetailed(lane.id, {
+          prompt,
+          ...(tool !== lane.tool ? { tool } : {}),
+          ...(tool === "claude" ? { permissionMode: readDefaultMode() } : {}),
+        });
+        remember({ laneId: r.laneId, runId: r.runId, tool });
+      } catch (err) {
+        setPending(null);
+        setDraft(prompt);
+        setError(
+          t("sagi.startFailed", { error: err instanceof Error ? err.message : String(err) })
+        );
+      } finally {
+        setStarting(false);
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [chat, starting, t, onLocal]
+  );
+
+  // New chat: the old one's session is stopped, not left running unseen —
+  // asking first only while it is still writing a reply.
+  const newChat = async () => {
+    if (chat) {
+      if (
+        busy &&
+        !(await confirmDialog({
+          title: t("sagi.chat.endTitle"),
+          message: t("sagi.chat.endBody"),
+          confirmLabel: t("sagi.chat.endConfirm"),
+          destructive: true,
+        }))
+      )
+        return;
+      try {
+        await api.run.kill(chat.runId, { archive: true });
+      } catch (err) {
+        toast.error(err);
+        return;
+      }
+    }
+    remember(null);
+    setLocal([]);
+    setPending(null);
+    setError(null);
+  };
+
+  const submit = (e?: FormEvent) => {
+    e?.preventDefault();
+    if (!draft.trim()) return;
+    const text = draft;
+    setDraft("");
+    void send(text);
+  };
+
+  const toolLabel = chat?.tool ?? petChatTool() ?? "claude";
+  const empty = lines.length === 0 && !pending;
+
+  return (
+    <div
+      className="pet-chat flex h-[30rem] max-h-[calc(100vh-6rem)] w-80 flex-col overflow-hidden rounded-3xl border border-border-light shadow-2xl animate-slide-up"
+      role="dialog"
+      aria-label={t("sagi.chat.label", { name })}
+    >
+      {/* header */}
+      <div className="pet-chat-head flex items-center gap-1 px-2 py-2">
+        <span className="pl-1.5 text-base leading-none" aria-hidden>
+          🐾
+        </span>
+        <div className="min-w-0 flex-1 px-1">
+          {title ?? <div className="truncate text-sm font-semibold text-fg-primary">{name}</div>}
+          <div className="flex items-center gap-1 text-[10px] uppercase tracking-wider text-fg-muted">
+            <span
+              className={`inline-block h-1.5 w-1.5 rounded-full ${
+                busy
+                  ? "animate-pulse bg-status-warning"
+                  : chat
+                    ? "bg-status-success"
+                    : "bg-fg-muted"
+              }`}
+              aria-hidden
+            />
+            {busy ? t("sagi.chat.typing") : toolLabel}
+          </div>
+        </div>
+        {headerActions}
+        {chat && (
+          <IconButton
+            label={t("sagi.chat.openWorkspace")}
+            onClick={() => onOpenWorkspace(chat.laneId, chat.runId)}
+          >
+            <ExternalLink size={15} />
+          </IconButton>
+        )}
+        <IconButton
+          label={t("sagi.chat.new")}
+          onClick={() => void newChat()}
+          disabled={(!chat && !local.length) || starting}
+        >
+          <SquarePen size={15} />
+        </IconButton>
+        <IconButton label={t("sagi.chat.close", { name })} onClick={onClose}>
+          <X size={16} />
+        </IconButton>
+      </div>
+
+      {info}
+
+      {/* conversation */}
+      <div ref={listRef} className="flex-1 space-y-2 overflow-y-auto px-3 py-3">
+        {empty && (
+          <div className="flex h-full flex-col items-center justify-center gap-2 px-4 text-center">
+            <span className="text-3xl" aria-hidden>
+              🐾
+            </span>
+            <p className="text-sm font-medium text-fg-primary">
+              {t("sagi.chat.emptyTitle", { name })}
+            </p>
+            <p className="text-xs text-fg-muted">{t("sagi.chat.emptyHint", { tool: toolLabel })}</p>
+          </div>
+        )}
+        {lines.map((l) =>
+          l.role === "tools" ? (
+            <div key={l.key} className="flex justify-start">
+              <span className="pet-chat-tools inline-flex max-w-[85%] items-center gap-1 truncate rounded-full px-2 py-0.5 text-[10px] text-fg-muted">
+                <Wrench size={10} className="shrink-0" aria-hidden />
+                <span className="truncate">{toolSummary(l.names)}</span>
+              </span>
+            </div>
+          ) : l.role === "user" ? (
+            <div key={l.key} className="flex justify-end">
+              <div className="max-w-[85%] whitespace-pre-wrap break-words rounded-2xl rounded-br-md bg-accent-solid px-3 py-2 text-sm text-white shadow-sm">
+                {l.text}
+              </div>
+            </div>
+          ) : (
+            <div key={l.key} className="flex justify-start">
+              <div className="pet-chat-reply max-w-[90%] break-words rounded-2xl rounded-bl-md px-3 py-2 text-sm text-fg-primary shadow-sm">
+                <MarkdownContent text={l.text} dense prose />
+              </div>
+            </div>
+          )
+        )}
+        {pending && (
+          <div className="flex justify-end">
+            <div className="max-w-[85%] whitespace-pre-wrap break-words rounded-2xl rounded-br-md bg-accent-solid px-3 py-2 text-sm text-white opacity-70 shadow-sm">
+              {pending}
+            </div>
+          </div>
+        )}
+        {busy && !menu && (
+          <div className="flex justify-start" aria-label={t("sagi.chat.typing")}>
+            <div className="pet-chat-reply flex gap-1 rounded-2xl rounded-bl-md px-3 py-3 shadow-sm">
+              <span className="pet-chat-dot" />
+              <span className="pet-chat-dot" />
+              <span className="pet-chat-dot" />
+            </div>
+          </div>
+        )}
+        {starting && (
+          <p className="flex items-center justify-center gap-1.5 text-[11px] text-fg-muted">
+            <Loader2 size={12} className="animate-spin" aria-hidden />
+            {t("sagi.chat.starting", { tool: toolLabel })}
+          </p>
+        )}
+        {chat && !sessionId && !starting && (
+          <p className="text-center text-[11px] text-fg-muted">{t("sagi.chat.notStarted")}</p>
+        )}
+      </div>
+
+      {error && (
+        <p className="mx-3 mb-1 rounded-lg bg-status-danger/10 px-2 py-1 text-[11px] text-status-danger">
+          {error}
+        </p>
+      )}
+
+      {/* prompt, or the question the CLI asks */}
+      <div className="pet-chat-foot px-2.5 py-2.5">
+        {menu && chat ? (
+          <div className="max-h-56 overflow-y-auto">
+            <PaneMenuCard
+              menu={menu}
+              onChoose={(i) => {
+                if (chooseRunOption(chat.runId, menu, i)) setMenu(null);
+                else setError(t("sagi.chat.notSent"));
+              }}
+              onAnswer={(text) => {
+                if (answerRunMenu(chat.runId, menu, text)) setMenu(null);
+                else setError(t("sagi.chat.notSent"));
+              }}
+              onCancel={() => {
+                if (interruptRun(chat.runId)) setMenu(null);
+                else setError(t("sagi.chat.notSent"));
+              }}
+            />
+          </div>
+        ) : (
+          <form onSubmit={submit} className="flex items-end gap-1.5">
+            <textarea
+              rows={1}
+              autoFocus
+              className="max-h-28 min-h-[2.25rem] flex-1 resize-none rounded-2xl border border-border bg-surface-1 px-3.5 py-2 text-sm text-fg-primary placeholder-fg-muted focus:border-accent focus:outline-none focus:ring-1 focus:ring-accent/30"
+              placeholder={t("sagi.chat.placeholder", { name })}
+              aria-label={t("sagi.chat.placeholder", { name })}
+              value={draft}
+              onChange={(e) => setDraft(e.target.value)}
+              onKeyDown={(e) => {
+                if (isSubmitEnter(e) && !e.shiftKey) {
+                  e.preventDefault();
+                  submit();
+                } else if (e.key === "Escape") {
+                  e.stopPropagation();
+                  e.nativeEvent.stopImmediatePropagation();
+                  onClose();
+                }
+              }}
+            />
+            <button
+              type="submit"
+              disabled={!draft.trim() || starting}
+              className="flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-accent-solid text-white shadow-sm transition-opacity hover:opacity-90 disabled:opacity-40"
+              aria-label={t("sagi.panel.send")}
+            >
+              <ArrowUp size={16} />
+            </button>
+          </form>
+        )}
+      </div>
+
+      {/* The chat's pane, attached off-screen: the only way a follow-up or a
+          menu answer reaches it. A real size, so tmux does not shrink the pane. */}
+      {chat && (
+        <div className="pet-chat-term" aria-hidden>
+          <TerminalView
+            runId={chat.runId}
+            wsBaseUrl={window.location.origin.replace(/^http/, "ws")}
+            autoFocus={false}
+            // The pane ended: the conversation stays on screen, the next
+            // message starts a new session.
+            onExit={() => {
+              writePetChat(null);
+              setChat(null);
+            }}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+function IconButton({
+  label,
+  onClick,
+  disabled,
+  children,
+}: {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+  children: React.ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      className="rounded-full p-1.5 text-fg-muted transition-colors hover:bg-surface-4 hover:text-fg-primary disabled:cursor-not-allowed disabled:opacity-40"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={label}
+      title={label}
+    >
+      {children}
+    </button>
+  );
+}

client/src/components/Sagi/PetSprite.tsx

@@ -8,7 +8,9 @@
  * 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
+ * Codex's own pet; a `moment` (a new session waves, a finish jumps, an error
+ * fails, a wait waits, a new subagent reviews — `useSagiBrain`) plays its row
+ * over the mood's, under the action; a v2 pet at idle holds the gaze pose `gaze` names. An
  * uploaded image is shown still and bobs with the same `data-mood` CSS as
  * Sagi. Reduced motion holds the row's first frame. A sprite that fails to
  * load (deleted from another browser) calls `onBroken`, so the mascot falls
@@ -18,7 +20,7 @@
 
 import { useEffect, useState } from "react";
 import { api } from "../../lib/api";
-import type { Mood } from "./brain";
+import type { Mood, PetMoment } from "./brain";
 
 const CELL = { w: 192, h: 208 };
 const COLS = 8;
@@ -58,12 +60,18 @@ const ROW: Record<Mood, number> = {
 /** What the user is doing to the pet, which outranks its mood. */
 export type PetAction = "run-left" | "run-right" | "wave";
 const ACTION_ROW: Record<PetAction, number> = { "run-right": 1, "run-left": 2, wave: 3 };
+/** A moment's row: wave, jump, failed, waiting, review. It outranks the mood,
+ *  and the user's own action outranks it. */
+const MOMENT_ROW: Record<PetMoment, number> = { wave: 3, jump: 4, fail: 5, wait: 6, review: 8 };
+/** Loops of a row before the sprite rests on its first frame. */
+const SPRITE_LOOPS = 4;
 
 export function PetSprite({
   id,
   kind,
   mood,
   action,
+  moment,
   gaze,
   size,
   reducedMotion,
@@ -73,6 +81,7 @@ export function PetSprite({
   kind: "codex" | "image";
   mood: Mood;
   action?: PetAction | null;
+  moment?: PetMoment | null;
   /** Gaze pose 0–15 (0 = up, clockwise), or none. Only a v2 sheet has them. */
   gaze?: number | null;
   size: number;
@@ -80,8 +89,8 @@ export function PetSprite({
   onBroken: () => void;
 }) {
   const url = api.pets.spriteUrl(id);
-  const row = action ? ACTION_ROW[action] : (ROW[mood] ?? 0);
-  const sleeping = !action && mood === "sleeping";
+  const row = action ? ACTION_ROW[action] : moment ? MOMENT_ROW[moment] : (ROW[mood] ?? 0);
+  const sleeping = !action && !moment && mood === "sleeping";
   // The cell on show, tagged with the row it was played for: a cell left over
   // from the previous row (say column 7 of a run) is never drawn on the next.
   const [cell, setCell] = useState({ of: row, row, col: 0 });
@@ -95,13 +104,17 @@ export function PetSprite({
     const own = play(row, sleeping ? SLEEP_SLOWDOWN : 1);
     let list = MOMENTS.has(row) ? [...own, ...own, ...own] : own;
     let i = 0;
+    let loops = 0;
     let timer = 0;
-    // `i` always indexes `list`: it wraps at its end.
+    // `i` always indexes `list`: it wraps at its end. A few loops, then the
+    // first frame rests — a sprite that never stops re-paints the page several
+    // times a second for as long as it is open; a new mood or action plays again.
     const tick = () => {
       timer = window.setTimeout(() => {
         if (++i === list.length) {
           i = 0;
           if (MOMENTS.has(row)) list = play(0);
+          if (++loops >= SPRITE_LOOPS) return setCell(list[0]!);
         }
         setCell(list[i]!);
         tick();
@@ -132,6 +145,7 @@ export function PetSprite({
         src={url}
         alt=""
         data-mood={mood}
+        data-moment={moment ?? undefined}
         className="sagi-pet-image"
         width={size}
         height={size}
@@ -141,7 +155,8 @@ export function PetSprite({
       />
     );
   }
-  const pose = gaze != null && rows > GAZE_ROW && !action && mood === "idle" ? gaze : null;
+  const pose =
+    gaze != null && rows > GAZE_ROW && !action && !moment && mood === "idle" ? gaze : null;
   const shown =
     pose != null
       ? { row: GAZE_ROW + Math.floor(pose / COLS), col: pose % COLS }

client/src/components/Sagi/Sagi.tsx

@@ -5,17 +5,20 @@
  *   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
+ *   Clicking the pet opens its chat window (`PetChat`), which is its whole UI:
+ *   the status strip (`SagiInfo`) sits on top, a question the pet can answer
+ *   itself is answered there, anything else goes to the AI.
+ *   Owns the open/closed chat state, the ⌘B / Esc shortcuts, reduced-motion
  *   detection, and route navigation. Reactive personality + status/Ask come
  *   from useSagiBrain; the avatar is draggable (AssistiveTouch-style) via
  *   useSagiPosition (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
- *   the "Sagi" workspace carrying it as the first prompt, then opens that
- *   workspace's session view (`/workspace?lane=<id>&run=<runId>`) — no new LLM
- *   backend. ⌘B/Ctrl+B is taken only while the mascot is shown and focus is not
+ *   The "do the job" path: an unmatched question is the chat's — it starts a
+ *   session of the default AI tool in the "Sagi" workspace; a default tool the
+ *   chat cannot read back starts there and its session view opens
+ *   (`/workspace?lane=<id>&run=<runId>`) — no new LLM backend. ⌘B/Ctrl+B is taken only while the mascot is shown and focus is not
  *   in an editable field (a terminal's Ctrl+B is tmux's prefix).
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
@@ -39,7 +42,7 @@
  * ## Internal dependencies
  * - `./SagiAvatar`
  * - `./SpeechBubble`
- * - `./SagiPanel`
+ * - `./SagiInfo`
  * - `./useSagiBrain`
  * - `./useSagiPosition`
  * - `./intents`
@@ -77,18 +80,32 @@ import {
   type ReactNode,
 } from "react";
 import { useNavigate } from "react-router-dom";
+import { useSettingsHref } from "../../lib/settingsLink";
+import { usePrefersReducedMotion } from "../../hooks/usePrefersReducedMotion";
 import { useTranslation } from "react-i18next";
 import { SagiAvatar } from "./SagiAvatar";
 import { PetSprite } from "./PetSprite";
 import { PetMenu } from "./PetMenu";
 import { SpeechBubble } from "./SpeechBubble";
-import { SagiPanel } from "./SagiPanel";
+import { PetNameButton, SagiInfo } from "./SagiInfo";
 import { useSagiBrain } from "./useSagiBrain";
 import { useSagiPosition } from "./useSagiPosition";
 import { useSagiEnabled } from "./SagiMount";
 import { matchIntent } from "./intents";
-import { sagiPrefs } from "./prefs";
+import { petName, sagiPrefs } from "./prefs";
+import type { SagiSubject } from "./brain";
 import { api } from "../../lib/api";
+import { readDefaultTool } from "../../lib/sessionDefaults";
+import { startInFreeTabDetailed } from "../lanes/startSession";
+import { workspaceHref } from "../SessionRowMenu";
+import { Heart } from "lucide-react";
+import { PetChat, petChatTool, type PetLocalReply } from "./PetChat";
+
+// Stroking: this many left/right turns of the pointer over the pet, within
+// STROKE_MS and with no button held, is a pat; then a pause before the next.
+const STROKE_TURNS = 4;
+const STROKE_MS = 1200;
+const STROKE_COOLDOWN_MS = 1500;
 import "./sagi.css";
 
 const FLYOUT_GAP = 10; // px between avatar and flyout
@@ -114,38 +131,27 @@ interface Anchor {
   dragging: boolean;
 }
 
-/** The OS "reduce motion" preference, followed live. */
-export function usePrefersReducedMotion(): boolean {
-  const [reduced, setReduced] = useState(
-    () =>
-      typeof window !== "undefined" &&
-      window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
-  );
-  useEffect(() => {
-    const mq = window.matchMedia?.("(prefers-reduced-motion: reduce)");
-    if (!mq) return;
-    const onChange = () => setReduced(mq.matches);
-    mq.addEventListener?.("change", onChange);
-    return () => mq.removeEventListener?.("change", onChange);
-  }, []);
-  return reduced;
-}
-
 /**
  * Fixed-position wrapper that places its content next to the avatar and clamps
  * it inside the viewport. It measures itself (and re-measures on content/size
  * changes via ResizeObserver) so a tall panel near a screen edge slides fully
  * into view instead of being cropped.
  */
-/** `front`: above the mascot itself — the pet menu, which may overlap it. */
+/**
+ * `front`: above the mascot itself — the pet menu, which may overlap it.
+ * `beside`: at the mascot's side instead of above it — the chat window, on the
+ * screen side away from the edge it docks to, its bottom level with the pet's.
+ */
 function SagiFlyout({
   anchor,
   children,
   front = false,
+  beside = false,
 }: {
   anchor: Anchor;
   children: ReactNode;
   front?: boolean;
+  beside?: boolean;
 }) {
   const ref = useRef<HTMLDivElement>(null);
   const [style, setStyle] = useState<CSSProperties>({ visibility: "hidden" });
@@ -158,6 +164,18 @@ function SagiFlyout({
     const vw = window.innerWidth;
     const vh = window.innerHeight;
 
+    if (beside) {
+      let left =
+        anchor.side === "left"
+          ? anchor.left + anchor.size + FLYOUT_GAP
+          : anchor.left - w - FLYOUT_GAP;
+      left = Math.min(vw - w - VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, left));
+      let top = anchor.top + anchor.size - h;
+      top = Math.min(vh - h - VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, top));
+      setStyle({ left, top, visibility: "visible" });
+      return;
+    }
+
     // Horizontal: hug the avatar's docked edge, then clamp on-screen.
     let left = anchor.side === "left" ? anchor.left : anchor.left + anchor.size - w;
     left = Math.min(vw - w - VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, left));
@@ -170,7 +188,7 @@ function SagiFlyout({
     top = Math.min(vh - h - VIEWPORT_MARGIN, Math.max(VIEWPORT_MARGIN, top));
 
     setStyle({ left, top, visibility: "visible" });
-  }, [anchor.left, anchor.top, anchor.size, anchor.side, anchor.openUp]);
+  }, [anchor.left, anchor.top, anchor.size, anchor.side, anchor.openUp, beside]);
 
   useLayoutEffect(() => {
     place();
@@ -208,13 +226,17 @@ export function Sagi() {
 function SagiBody() {
   const { t } = useTranslation("settings");
   const [pet, setPet] = useState(() => sagiPrefs.getPet());
+  // The name it goes by: the user's nickname, the pet's own, else Sagi.
+  const [name, setName] = useState(() => petName(sagiPrefs.getPet()));
   const [size, setSize] = useState(() => sagiPrefs.getSize());
+  // The chat window (PetChat.tsx): the pet's whole UI.
   const [open, setOpen] = useState(false);
   // The right-click pet menu (`PetMenu.tsx`).
   const [menu, setMenu] = useState(false);
   const [hover, setHover] = useState(false);
   const reducedMotion = usePrefersReducedMotion();
   const navigate = useNavigate();
+  const href = useSettingsHref();
   const brain = useSagiBrain();
   const place = useSagiPosition(size);
 
@@ -224,11 +246,32 @@ function SagiBody() {
     () =>
       sagiPrefs.subscribe(() => {
         setPet(sagiPrefs.getPet());
+        setName(petName(sagiPrefs.getPet()));
         setSize(sagiPrefs.getSize());
       }),
     []
   );
 
+  // A pet worn before names rode along with the choice: look its name up once.
+  const petId = pet.id;
+  const unnamed = "kind" in pet && !pet.name;
+  useEffect(() => {
+    if (!unnamed) return;
+    let live = true;
+    api.pets
+      .list()
+      .then((list) => {
+        const found = list.pets.find((p) => p.id === petId);
+        const cur = sagiPrefs.getPet();
+        if (live && found && cur.id === petId && "kind" in cur)
+          sagiPrefs.setPet({ ...cur, name: found.displayName });
+      })
+      .catch(() => undefined);
+    return () => {
+      live = false;
+    };
+  }, [petId, unnamed]);
+
   // ⌘B / Ctrl+B toggles the panel; Esc closes it. Only while the mascot is
   // shown, and never from an editable field, where Ctrl+B belongs to the field.
   useEffect(() => {
@@ -279,27 +322,48 @@ function SagiBody() {
     [navigate]
   );
 
-  const onAsk = useCallback(
-    (query: string): string | null => {
-      const result = matchIntent(query, brain.status);
-      if (result.kind === "answer") return result.text;
-      // Handoff: ensure the "Sagi" lane exists for this dashboard, spawn a
-      // fresh claude session in it carrying the user's prompt as its first
-      // message, then open that workspace's session view on the new pane.
-      // Fire-and-forget — the panel already clears its composer on null and
-      // closes; errors surface as an answer instead of silently swallowing.
+  // A session a bubble or the panel names: its live pane when a dashboard run
+  // holds it, else its workspace's replay, else its analysis page. Opening
+  // never resumes anything.
+  const openSession = useCallback(
+    (s: SagiSubject) => {
+      const go = (runs?: Parameters<typeof workspaceHref>[1]) => {
+        navigate(workspaceHref(s, runs) ?? `/sessions/${encodeURIComponent(s.id)}`);
+        brain.dismissBubble();
+        setOpen(false);
+      };
+      api.run
+        .list()
+        .then((r) => go(r.items))
+        .catch(() => go());
+    },
+    [brain, navigate]
+  );
+
+  // Asked by the chat before any session runs.
+  const onLocal = useCallback(
+    (query: string): PetLocalReply => {
+      const result = matchIntent(query, brain.status, { name, attention: brain.attention });
+      if (result.kind === "answer") {
+        if (result.moment) brain.playMoment(result.moment);
+        return { answer: result.text };
+      }
+      // A question the pet cannot answer: the chat starts a session of the
+      // default AI tool and shows it as chat.
+      if (petChatTool()) return null;
+      // A default tool the chat cannot read back (not Claude/Codex): start it
+      // in the "Sagi" workspace and open its pane there, as before.
       const prompt = result.prompt;
       brain.setThinking(true);
       (async () => {
         try {
           const { lane } = await api.lanes.ensure({ title: "Sagi" });
-          const run = await api.run.start({
-            laneId: lane.id,
-            cwd: lane.cwd,
-            initialPrompt: prompt,
-            permissionMode: "acceptEdits",
+          const tool = readDefaultTool();
+          const r = await startInFreeTabDetailed(lane.id, {
+            prompt,
+            ...(tool && tool !== lane.tool ? { tool } : {}),
           });
-          navigate(`/workspace?lane=${lane.id}&run=${encodeURIComponent(run.id)}`);
+          navigate(`/workspace?lane=${r.laneId}&run=${encodeURIComponent(r.runId)}`);
           setOpen(false);
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -308,11 +372,34 @@ function SagiBody() {
           brain.setThinking(false);
         }
       })();
-      return null;
+      return { handled: true };
     },
-    [brain, navigate, t]
+    [brain, navigate, t, name]
   );
 
+  // Stroke the pet (move the pointer back and forth over it) to pat it.
+  const stroke = useRef({ dir: 0, x: 0, turns: [] as number[], until: 0 });
+  const onStroke = (e: React.PointerEvent) => {
+    if (e.buttons !== 0 || e.pointerType === "touch") return;
+    const s = stroke.current;
+    const now = performance.now();
+    const dx = e.clientX - s.x;
+    s.x = e.clientX;
+    if (Math.abs(dx) < 2 || now < s.until) return;
+    const dir = Math.sign(dx);
+    if (s.dir && dir !== s.dir) {
+      s.turns = [...s.turns.filter((t0) => now - t0 < STROKE_MS), now];
+      if (s.turns.length >= STROKE_TURNS) {
+        s.turns = [];
+        s.until = now + STROKE_COOLDOWN_MS;
+        brain.pat();
+      }
+    }
+    s.dir = dir;
+  };
+
+  const onBusy = useCallback((b: boolean) => brain.setThinking(b), [brain.setThinking]);
+
   const anchor: Anchor = {
     left: place.left,
     top: place.top,
@@ -324,18 +411,51 @@ function SagiBody() {
 
   return (
     <>
-      {/* The panel is too big to drag around, so it hides mid-drag. The bubble
-          does not - it is Sagi talking, and it has to stay by its mouth. */}
-      {!place.dragging && open && (
-        <SagiFlyout anchor={anchor}>
-          <SagiPanel
-            status={brain.status}
-            muted={brain.muted}
-            onToggleMute={brain.toggleMute}
-            onClearAlerts={brain.clearAlerts}
-            onNavigate={onNavigate}
-            onAsk={onAsk}
+      {/* Beside the pet, riding along with it mid-drag too (SagiFlyout follows
+          it 1:1). Closing unmounts it; its chat is remembered, so reopening
+          re-attaches the same session. */}
+      {open && (
+        <SagiFlyout anchor={anchor} beside>
+          <PetChat
+            name={name}
+            title={
+              <PetNameButton
+                name={name}
+                ownName={"kind" in pet ? pet.name || "Sagi" : "Sagi"}
+                nickname={sagiPrefs.getNickname(pet.id)}
+                onRename={(next) => sagiPrefs.setNickname(pet.id, next)}
+              />
+            }
+            headerActions={
+              <button
+                type="button"
+                className="rounded-full p-1.5 text-fg-muted transition-colors hover:bg-surface-4 hover:text-status-danger"
+                onClick={brain.pat}
+                aria-label={t("sagi.panel.pat", { name })}
+                title={t("sagi.panel.pat", { name })}
+              >
+                <Heart size={15} />
+              </button>
+            }
+            info={
+              <SagiInfo
+                attention={brain.attention}
+                onOpenSession={openSession}
+                status={brain.status}
+                muted={brain.muted}
+                onToggleMute={brain.toggleMute}
+                onClearAlerts={brain.clearAlerts}
+                onNavigate={onNavigate}
+                defaultOpen={brain.attention.length > 0}
+              />
+            }
+            onLocal={onLocal}
             onClose={() => setOpen(false)}
+            onOpenWorkspace={(laneId, runId) => {
+              navigate(`/workspace?lane=${laneId}&run=${encodeURIComponent(runId)}`);
+              setOpen(false);
+            }}
+            onBusy={onBusy}
           />
         </SagiFlyout>
       )}
@@ -348,7 +468,7 @@ function SagiBody() {
             onClose={() => setMenu(false)}
             onSettings={() => {
               setMenu(false);
-              navigate("/settings/appearance#pet");
+              navigate(href("appearance#pet"));
             }}
           />
         </SagiFlyout>
@@ -356,7 +476,11 @@ function SagiBody() {
 
       {!open && !menu && brain.bubble && (
         <SagiFlyout anchor={anchor}>
-          <SpeechBubble text={brain.bubble} onDismiss={brain.dismissBubble} />
+          <SpeechBubble
+            bubble={brain.bubble}
+            onDismiss={brain.dismissBubble}
+            onOpen={openSession}
+          />
         </SagiFlyout>
       )}
 
@@ -368,7 +492,10 @@ function SagiBody() {
         onPointerEnter={() => setHover(true)}
         onPointerLeave={() => setHover(false)}
         onPointerDown={place.onPointerDown}
-        onPointerMove={place.onPointerMove}
+        onPointerMove={(e) => {
+          place.onPointerMove(e);
+          onStroke(e);
+        }}
         onPointerUp={place.onPointerUp}
         onKeyDown={place.onKeyDown}
         onClick={() => {
@@ -383,19 +510,27 @@ function SagiBody() {
           setOpen(false);
           setMenu(true);
         }}
-        aria-label={open ? t("sagi.closeAvatar") : t("sagi.open")}
+        aria-label={open ? t("sagi.closeAvatar", { name }) : t("sagi.open", { name })}
         aria-expanded={open}
-        title={t("sagi.avatarTitle")}
+        title={t("sagi.avatarTitle", { name })}
       >
         {pet.id === "sagi" || !("kind" in pet) ? (
-          <SagiAvatar mood={brain.mood} reducedMotion={reducedMotion} size={size} />
+          <SagiAvatar
+            mood={brain.mood}
+            moment={reducedMotion ? null : brain.moment?.kind}
+            reducedMotion={reducedMotion}
+            size={size}
+          />
         ) : (
           <PetSprite
             id={pet.id}
             kind={pet.kind}
             mood={brain.mood}
             // Dragged → runs that way; hovered → waves (Codex's pet does both).
-            action={place.moving ? `run-${place.moving}` : hover ? "wave" : null}
+            // A moment (a pat's hop) outranks the hover wave, or stroking the
+            // pet would only ever show it waving.
+            action={place.moving ? `run-${place.moving}` : hover && !brain.moment ? "wave" : null}
+            moment={brain.moment?.kind}
             gaze={gaze}
             size={size}
             reducedMotion={reducedMotion}
@@ -403,10 +538,28 @@ function SagiBody() {
             onBroken={() => sagiPrefs.setPet({ id: "sagi" })}
           />
         )}
-        {brain.status.errorCount > 0 && (
+        {brain.reaction && (
+          <span key={brain.reaction.key} className="sagi-reaction" aria-live="polite">
+            <span className="sagi-hearts" aria-hidden>
+              <span>💜</span>
+              <span>💗</span>
+              <span>💜</span>
+            </span>
+            <span className="sagi-reaction-text" data-side={place.side}>
+              {brain.reaction.text}
+            </span>
+          </span>
+        )}
+        {brain.status.errorCount > 0 ? (
           <span className="sagi-error-dot" aria-hidden>
             {brain.status.errorCount > 9 ? "9+" : brain.status.errorCount}
           </span>
+        ) : (
+          brain.status.waitingCount > 0 && (
+            <span className="sagi-error-dot" data-kind="waiting" aria-hidden>
+              {brain.status.waitingCount > 9 ? "9+" : brain.status.waitingCount}
+            </span>
+          )
         )}
       </button>
     </>

client/src/components/Sagi/SagiAvatar.tsx

@@ -37,12 +37,14 @@
  * ============================================================================= */
 
 import { memo, useEffect, useRef } from "react";
-import type { Mood } from "./brain";
+import type { Mood, PetMoment } from "./brain";
 
 interface SagiAvatarProps {
   mood: Mood;
   reducedMotion: boolean;
   size?: number;
+  /** A one-shot reaction (hop, wiggle, flinch…) played over the mood. */
+  moment?: PetMoment | null;
 }
 
 const MAX_PUPIL_SHIFT = 36; // px in the 1280-unit path coordinate space
@@ -88,6 +90,7 @@ export const SagiAvatar = memo(function SagiAvatar({
   mood,
   reducedMotion,
   size = 68,
+  moment = null,
 }: SagiAvatarProps) {
   const rootRef = useRef<SVGSVGElement | null>(null);
   const rafRef = useRef<number>();
@@ -148,6 +151,7 @@ export const SagiAvatar = memo(function SagiAvatar({
       ref={rootRef}
       className="sagi-avatar"
       data-mood={mood}
+      data-moment={moment ?? undefined}
       data-reduced={reducedMotion ? "1" : "0"}
       width={size}
       height={size}

client/src/components/Sagi/SagiInfo.tsx

@@ -0,0 +1,297 @@
+/**
+ * @file SagiInfo.tsx
+ * @description What the pet knows, shown inside its chat window (`PetChat`):
+ *   the name you rename by clicking it (`PetNameButton`), and a status strip
+ *   (`SagiInfo`) — live / waiting / errored counts and the connection state
+ *   always in sight, and on expanding, the sessions that need the user, by
+ *   name, plus Mute and Clear alerts. Pure presentational: all data and
+ *   behavior are injected by the container (`Sagi.tsx`).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useState } from "react";
+import {
+  AlertTriangle,
+  Bell,
+  BellOff,
+  ChevronDown,
+  ChevronRight,
+  Hourglass,
+  Radio,
+  Trash2,
+  type LucideIcon,
+} from "lucide-react";
+import { useTranslation } from "react-i18next";
+import { subjectLabel, type AttentionItem, type SagiStatus, type SagiSubject } from "./brain";
+import { PET_NAME_MAX } from "./prefs";
+
+/** How many sessions the "Needs you" list shows before pointing at Sessions. */
+const ATTENTION_SHOWN = 4;
+
+/** The pet's name; a click renames it in place (empty = its own name). */
+export function PetNameButton({
+  name,
+  ownName,
+  nickname,
+  onRename,
+}: {
+  name: string;
+  ownName: string;
+  nickname: string;
+  onRename: (name: string) => void;
+}) {
+  const { t } = useTranslation("settings");
+  // The name being typed, or null while not renaming.
+  const [renaming, setRenaming] = useState<string | null>(null);
+  const save = () => {
+    if (renaming === null) return;
+    onRename(renaming);
+    setRenaming(null);
+  };
+  return renaming === null ? (
+    <button
+      type="button"
+      className="max-w-full truncate rounded px-0.5 text-sm font-semibold text-fg-primary hover:bg-surface-4"
+      onClick={() => setRenaming(nickname)}
+      aria-label={t("sagi.panel.rename", { name })}
+      title={t("sagi.panel.rename", { name })}
+    >
+      {name}
+    </button>
+  ) : (
+    <input
+      autoFocus
+      className="w-28 rounded border border-accent bg-surface-1 px-1 py-0.5 text-sm text-fg-primary focus:outline-none"
+      value={renaming}
+      maxLength={PET_NAME_MAX}
+      placeholder={ownName}
+      aria-label={t("sagi.panel.renameLabel")}
+      title={t("sagi.panel.renameHint")}
+      onChange={(e) => setRenaming(e.target.value)}
+      onBlur={save}
+      onKeyDown={(e) => {
+        if (e.key === "Enter") {
+          e.preventDefault();
+          save();
+        } else if (e.key === "Escape") {
+          // Esc cancels the rename only, not the whole chat.
+          e.stopPropagation();
+          e.nativeEvent.stopImmediatePropagation();
+          setRenaming(null);
+        }
+      }}
+    />
+  );
+}
+
+interface SagiInfoProps {
+  attention: ReadonlyArray<AttentionItem>;
+  onOpenSession: (s: SagiSubject) => void;
+  status: SagiStatus;
+  muted: boolean;
+  onToggleMute: () => void;
+  onClearAlerts: () => void;
+  onNavigate: (route: string) => void;
+  /** Expanded at first: the sessions that need the user and the actions. */
+  defaultOpen?: boolean;
+}
+
+/** The status strip under the chat's header. */
+export function SagiInfo({
+  attention,
+  onOpenSession,
+  status,
+  muted,
+  onToggleMute,
+  onClearAlerts,
+  onNavigate,
+  defaultOpen = false,
+}: SagiInfoProps) {
+  const { t } = useTranslation("settings");
+  const [open, setOpen] = useState(defaultOpen);
+  const Chevron = open ? ChevronDown : ChevronRight;
+  return (
+    <div className="pet-chat-info border-b border-border/60 px-3 py-2">
+      <button
+        type="button"
+        className="flex w-full items-center gap-1.5 rounded-lg text-left"
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+        aria-label={t("sagi.chat.status")}
+        title={t("sagi.chat.status")}
+      >
+        <StatChip
+          icon={Radio}
+          label={t("sagi.panel.statLive")}
+          value={status.liveCount}
+          tone={status.liveCount > 0 ? "accent" : "muted"}
+        />
+        <StatChip
+          icon={Hourglass}
+          label={t("sagi.panel.statWaiting")}
+          value={status.waitingCount}
+          tone={status.waitingCount > 0 ? "amber" : "muted"}
+        />
+        <StatChip
+          icon={AlertTriangle}
+          label={t("sagi.panel.statErrored")}
+          value={status.errorCount}
+          tone={status.errorCount > 0 ? "red" : "muted"}
+        />
+        <span
+          className={`ml-auto inline-flex items-center gap-1 rounded-full px-1.5 py-0.5 text-[10px] font-medium ${
+            status.connected
+              ? "bg-status-success/15 text-status-success"
+              : "bg-status-danger/15 text-status-danger"
+          }`}
+        >
+          <span
+            className={`inline-block h-1.5 w-1.5 rounded-full ${
+              status.connected ? "bg-status-success" : "bg-status-danger"
+            }`}
+            aria-hidden
+          />
+          {status.connected ? t("sagi.panel.live") : t("sagi.panel.offline")}
+        </span>
+        <Chevron size={13} className="shrink-0 text-fg-muted" aria-hidden />
+      </button>
+
+      {open && (
+        <div className="mt-2 max-h-48 overflow-y-auto">
+          {/* the sessions that need the user, by name */}
+          {attention.length > 0 && (
+            <div className="mb-2">
+              <div className="mb-1 text-[10px] font-medium uppercase tracking-wider text-fg-muted">
+                {t("sagi.panel.attention")}
+              </div>
+              <ul className="space-y-1">
+                {attention.slice(0, ATTENTION_SHOWN).map((item) => (
+                  <li key={item.id}>
+                    <button
+                      className="group flex w-full items-center gap-2 rounded-lg bg-surface-1 px-2 py-1.5 text-left text-xs transition-colors hover:bg-surface-4"
+                      onClick={() => onOpenSession(item)}
+                      title={item.cwd ?? item.id}
+                    >
+                      {item.kind === "error" ? (
+                        <AlertTriangle
+                          size={13}
+                          className="shrink-0 text-status-danger"
+                          aria-hidden
+                        />
+                      ) : (
+                        <Hourglass size={13} className="shrink-0 text-status-warning" aria-hidden />
+                      )}
+                      <span className="min-w-0 flex-1 truncate text-fg-secondary group-hover:text-fg-primary">
+                        {subjectLabel(item)}
+                      </span>
+                      <span className="shrink-0 text-[10px] text-fg-muted">
+                        {item.kind === "error"
+                          ? t("sagi.panel.attentionError")
+                          : t("sagi.panel.attentionWaiting")}
+                      </span>
+                      <ChevronRight size={12} className="shrink-0 text-fg-muted" aria-hidden />
+                    </button>
+                  </li>
+                ))}
+              </ul>
+              {attention.length > ATTENTION_SHOWN && (
+                <button
+                  className="mt-1 text-[11px] text-accent hover:underline"
+                  onClick={() => onNavigate("/sessions")}
+                >
+                  {t("sagi.panel.attentionMore", { count: attention.length - ATTENTION_SHOWN })}
+                </button>
+              )}
+            </div>
+          )}
+
+          <div className="grid grid-cols-2 gap-1.5">
+            <ActionButton
+              icon={muted ? BellOff : Bell}
+              label={muted ? t("sagi.panel.unmute") : t("sagi.panel.mute")}
+              onClick={onToggleMute}
+            />
+            <ActionButton
+              icon={Trash2}
+              label={t("sagi.panel.clearAlerts")}
+              disabled={status.errorCount === 0}
+              onClick={onClearAlerts}
+            />
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface Tone {
+  wrap: string;
+  value: string;
+  icon: string;
+}
+
+const TONE_MUTED: Tone = {
+  wrap: "border-border bg-surface-1",
+  value: "text-fg-secondary",
+  icon: "text-fg-muted",
+};
+
+const TONES: Record<string, Tone> = {
+  accent: { wrap: "border-accent/30 bg-accent/10", value: "text-fg-primary", icon: "text-accent" },
+  amber: {
+    wrap: "border-status-warning/30 bg-status-warning/10",
+    value: "text-status-warning",
+    icon: "text-status-warning",
+  },
+  red: {
+    wrap: "border-status-danger/30 bg-status-danger/10",
+    value: "text-status-danger",
+    icon: "text-status-danger",
+  },
+  muted: TONE_MUTED,
+};
+
+/** One count, compact: icon, number, label on one line. */
+function StatChip({
+  icon: Icon,
+  label,
+  value,
+  tone,
+}: {
+  icon: LucideIcon;
+  label: string;
+  value: number;
+  tone: string;
+}) {
+  const t = TONES[tone] ?? TONE_MUTED;
+  return (
+    <span className={`inline-flex items-center gap-1 rounded-full border px-1.5 py-0.5 ${t.wrap}`}>
+      <Icon size={11} className={t.icon} aria-hidden />
+      <span className={`text-xs font-semibold tabular-nums ${t.value}`}>{value}</span>
+      <span className="text-[9px] uppercase tracking-wider text-fg-muted">{label}</span>
+    </span>
+  );
+}
+
+function ActionButton({
+  icon: Icon,
+  label,
+  onClick,
+  disabled,
+}: {
+  icon: LucideIcon;
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+}) {
+  return (
+    <button
+      className="flex w-full items-center gap-1.5 rounded-lg bg-surface-1 px-2 py-1.5 text-xs text-fg-secondary transition-colors hover:bg-surface-4 hover:text-fg-primary disabled:cursor-not-allowed disabled:opacity-40"
+      onClick={onClick}
+      disabled={disabled}
+    >
+      <Icon size={14} className="shrink-0" />
+      <span className="truncate">{label}</span>
+    </button>
+  );
+}

client/src/components/Sagi/SagiPanel.tsx

@@ -1,295 +0,0 @@
-/**
- * @file SagiPanel.tsx
- * @description Expanded Sagi panel: a live status strip (live / waiting /
- *   errored stat chips + connection state), quick navigation actions, and a
- *   local "Ask" box. Pure presentational - all data and the ask/navigation
- *   behavior are injected by the container.
- * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
- */
-/* =============================================================================
- * MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
- * =============================================================================
- * **Purpose:** Sagi is the optional on-screen mascot assistant — quips, intents, and lightweight event reactions layered above the dashboard chrome.
- *
- * ## Design constraints
- * - Local-first: no telemetry leaves the machine unless the user configures webhooks.
- * - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
- *   philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
- * - Destructive flows stay behind explicit confirmation modals and server-side gates.
- * - Internationalization: user-visible strings belong in i18n JSON, not literals here.
- *
- * ## Remote data & SSH
- * Remote Data Sources let operators aggregate multiple machines. SSH entries describe
- * how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
- * scoped GET via `?sources=`. Health checks and import history surface in Settings.
- *
- * ## Internal dependencies
- * - `./brain`
- *
- * ## Public surface
- * - `SagiPanel` — exported API; see TSDoc on the symbol for behavior.
- *
- * ## Testing pointers
- * - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
- * - Server contract changes require `npm run test:server` and OpenAPI sync.
- *
- * ## Related docs
- * - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
- * - `docs/API.md` — REST reference.
- * - `skills/file-headers/` — mandatory `@author` header policy.
- * ============================================================================= */
-/* -----------------------------------------------------------------------------
- * EXPORT CATALOG — quick index of symbols defined below (documentation only).
- * -----------------------------------------------------------------------------
- * **SagiPanel**
- *   Part of this module's public contract. Downstream imports should treat
- *   the signature and return type as stable unless release notes say otherwise.
- *   When behavior changes, update the `@file` overview and relevant tests.
- *
- * ----------------------------------------------------------------------------- */
-
-import { useState, type FormEvent, type ReactNode } from "react";
-import {
-  Play,
-  Activity,
-  LayoutList,
-  Bell,
-  BellOff,
-  Trash2,
-  X,
-  Send,
-  AlertTriangle,
-  Hourglass,
-  Radio,
-  type LucideIcon,
-} from "lucide-react";
-import { useTranslation } from "react-i18next";
-import type { SagiStatus } from "./brain";
-
-interface SagiPanelProps {
-  status: SagiStatus;
-  muted: boolean;
-  onToggleMute: () => void;
-  onClearAlerts: () => void;
-  onNavigate: (route: string) => void;
-  /** Returns an answer to display, or null when the query was handed off. */
-  onAsk: (query: string) => string | null;
-  onClose: () => void;
-}
-
-export function SagiPanel({
-  status,
-  muted,
-  onToggleMute,
-  onClearAlerts,
-  onNavigate,
-  onAsk,
-  onClose,
-}: SagiPanelProps) {
-  const { t } = useTranslation("settings");
-  const [query, setQuery] = useState("");
-  const [answer, setAnswer] = useState<string | null>(null);
-
-  const submit = (e: FormEvent) => {
-    e.preventDefault();
-    const result = onAsk(query);
-    setAnswer(result); // null means it handed off (container navigates/closes)
-    setQuery("");
-  };
-
-  return (
-    <div
-      className="w-72 overflow-hidden rounded-2xl border border-border-light bg-surface-2/95 shadow-2xl backdrop-blur-md animate-slide-up"
-      role="dialog"
-      aria-label={t("sagi.panel.label")}
-    >
-      {/* header */}
-      <div className="flex items-center justify-between gap-2 border-b border-border/70 bg-gradient-to-r from-accent/10 to-transparent px-3.5 py-2.5">
-        <div className="flex items-center gap-2 min-w-0">
-          <span className="text-base leading-none" aria-hidden>
-            🐾
-          </span>
-          <span className="text-sm font-semibold text-fg-primary">Sagi</span>
-          <span
-            className={`ml-0.5 inline-flex items-center gap-1 rounded-full px-1.5 py-0.5 text-[10px] font-medium ${
-              status.connected
-                ? "bg-status-success/15 text-status-success"
-                : "bg-status-danger/15 text-status-danger"
-            }`}
-          >
-            <span
-              className={`inline-block h-1.5 w-1.5 rounded-full ${
-                status.connected ? "bg-status-success" : "bg-status-danger"
-              }`}
-              aria-hidden
-            />
-            {status.connected ? t("sagi.panel.live") : t("sagi.panel.offline")}
-          </span>
-        </div>
-        <button
-          className="rounded-md p-1 text-fg-muted transition-colors hover:bg-surface-4 hover:text-fg-secondary"
-          onClick={onClose}
-          aria-label={t("sagi.panel.close")}
-        >
-          <X size={15} />
-        </button>
-      </div>
-
-      <div className="p-3">
-        {/* status stat chips */}
-        <div className="mb-3 grid grid-cols-3 gap-1.5">
-          <StatChip
-            icon={Radio}
-            label={t("sagi.panel.statLive")}
-            value={status.liveCount}
-            tone={status.liveCount > 0 ? "accent" : "muted"}
-          />
-          <StatChip
-            icon={Hourglass}
-            label={t("sagi.panel.statWaiting")}
-            value={status.waitingCount}
-            tone={status.waitingCount > 0 ? "amber" : "muted"}
-          />
-          <StatChip
-            icon={AlertTriangle}
-            label={t("sagi.panel.statErrored")}
-            value={status.errorCount}
-            tone={status.errorCount > 0 ? "red" : "muted"}
-          />
-        </div>
-
-        {/* quick actions */}
-        <div className="mb-3 grid grid-cols-2 gap-1.5">
-          <ActionButton
-            icon={Play}
-            label={t("sagi.panel.runClaude")}
-            onClick={() => onNavigate("/workspace")}
-          />
-          <ActionButton
-            icon={Activity}
-            label={t("sagi.panel.activity")}
-            onClick={() => onNavigate("/activity")}
-          />
-          <ActionButton
-            icon={LayoutList}
-            label={t("sagi.panel.sessions")}
-            onClick={() => onNavigate("/sessions")}
-          />
-          <ActionButton
-            icon={AlertTriangle}
-            label={t("sagi.panel.errored")}
-            disabled={status.errorCount === 0}
-            onClick={() => onNavigate("/sessions")}
-          />
-          <ActionButton
-            icon={muted ? BellOff : Bell}
-            label={muted ? t("sagi.panel.unmute") : t("sagi.panel.mute")}
-            onClick={onToggleMute}
-          />
-          <ActionButton
-            icon={Trash2}
-            label={t("sagi.panel.clearAlerts")}
-            disabled={status.errorCount === 0}
-            onClick={onClearAlerts}
-          />
-        </div>
-
-        {/* ask */}
-        <form onSubmit={submit} className="flex items-center gap-1.5">
-          <input
-            className="flex-1 rounded-lg border border-border bg-surface-1 px-2.5 py-1.5 text-xs text-fg-secondary placeholder-fg-muted transition-colors focus:border-accent focus:outline-none focus:ring-1 focus:ring-accent/30"
-            placeholder={t("sagi.panel.askPlaceholder")}
-            value={query}
-            onChange={(e) => setQuery(e.target.value)}
-            aria-label={t("sagi.panel.ask")}
-          />
-          <button
-            type="submit"
-            className="btn-primary justify-center px-2.5 py-2"
-            aria-label={t("sagi.panel.send")}
-          >
-            <Send size={14} />
-          </button>
-        </form>
-        {answer && (
-          <p className="mt-2 rounded-lg bg-surface-1/70 px-2.5 py-2 text-xs leading-relaxed text-fg-secondary">
-            {answer}
-          </p>
-        )}
-      </div>
-    </div>
-  );
-}
-
-interface Tone {
-  wrap: string;
-  value: string;
-  icon: string;
-}
-
-const TONE_MUTED: Tone = {
-  wrap: "border-border bg-surface-1",
-  value: "text-fg-secondary",
-  icon: "text-fg-muted",
-};
-
-const TONES: Record<string, Tone> = {
-  accent: { wrap: "border-accent/30 bg-accent/10", value: "text-fg-primary", icon: "text-accent" },
-  amber: {
-    wrap: "border-status-warning/30 bg-status-warning/10",
-    value: "text-status-warning",
-    icon: "text-status-warning",
-  },
-  red: {
-    wrap: "border-status-danger/30 bg-status-danger/10",
-    value: "text-status-danger",
-    icon: "text-status-danger",
-  },
-  muted: TONE_MUTED,
-};
-
-function StatChip({
-  icon: Icon,
-  label,
-  value,
-  tone,
-}: {
-  icon: LucideIcon;
-  label: string;
-  value: number;
-  tone: string;
-}): ReactNode {
-  const t = TONES[tone] ?? TONE_MUTED;
-  return (
-    <div className={`flex flex-col items-center gap-0.5 rounded-xl border py-1.5 ${t.wrap}`}>
-      <Icon size={13} className={t.icon} aria-hidden />
-      <span className={`text-base font-semibold leading-none tabular-nums ${t.value}`}>
-        {value}
-      </span>
-      <span className="text-[9px] uppercase tracking-wider text-fg-muted">{label}</span>
-    </div>
-  );
-}
-
-function ActionButton({
-  icon: Icon,
-  label,
-  onClick,
-  disabled,
-}: {
-  icon: LucideIcon;
-  label: string;
-  onClick: () => void;
-  disabled?: boolean;
-}) {
-  return (
-    <button
-      className="flex items-center gap-1.5 rounded-lg bg-surface-1 px-2 py-1.5 text-xs text-fg-secondary transition-colors hover:bg-surface-4 hover:text-fg-primary disabled:cursor-not-allowed disabled:opacity-40"
-      onClick={onClick}
-      disabled={disabled}
-    >
-      <Icon size={14} className="shrink-0" />
-      <span className="truncate">{label}</span>
-    </button>
-  );
-}

client/src/components/Sagi/SpeechBubble.tsx

@@ -1,14 +1,14 @@
 /**
  * @file SpeechBubble.tsx
  * @description Transient speech bubble rendered above the Sagi mascot.
- * Pure presentation — visibility timing and quip selection live in
- * {@link useSagiBrain}; this component only paints the bubble and handles
- * user dismissal.
+ * Pure presentation — visibility timing, coalescing and quip selection live in
+ * {@link useSagiBrain}; this component paints the line, the session(s) it is
+ * about, an Open button when it is about exactly one, and handles dismissal.
  *
  * ## Accessibility
  * Uses `role="status"` with `aria-live="polite"` so screen readers announce
- * new quips without interrupting current speech. Click anywhere on the bubble
- * to dismiss early.
+ * new quips without interrupting current speech. Click the bubble to dismiss
+ * it early; its Open button opens the session instead.
  *
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
@@ -52,30 +52,52 @@
  * ----------------------------------------------------------------------------- */
 
 import { useTranslation } from "react-i18next";
+import type { SagiBubble } from "./useSagiBrain";
+import type { SagiSubject } from "./brain";
 
 /** Props for {@link SpeechBubble}. */
 interface SpeechBubbleProps {
-  /** Quip text to display inside the bubble. */
-  text: string;
+  bubble: SagiBubble;
   /** Called when the user clicks to dismiss. */
   onDismiss: () => void;
+  /** Opens the session the bubble is about. */
+  onOpen?: (subject: SagiSubject) => void;
 }
 
 /**
  * Animated speech bubble above Sagi.
  * @param props See {@link SpeechBubbleProps}.
  */
-export function SpeechBubble({ text, onDismiss }: SpeechBubbleProps) {
+export function SpeechBubble({ bubble, onDismiss, onOpen }: SpeechBubbleProps) {
   const { t } = useTranslation("settings");
+  const { text, detail, subject, tone } = bubble;
   return (
     <div
       className="sagi-bubble sagi-bubble-enter"
+      data-tone={tone}
       role="status"
       aria-live="polite"
       onClick={onDismiss}
       title={t("sagi.bubbleDismiss")}
     >
-      {text}
+      <div>{text}</div>
+      {(detail || (subject && onOpen)) && (
+        <div className="sagi-bubble-detail">
+          {detail && <span className="sagi-bubble-subject">{detail}</span>}
+          {subject && onOpen && (
+            <button
+              type="button"
+              className="sagi-bubble-open"
+              onClick={(e) => {
+                e.stopPropagation();
+                onOpen(subject);
+              }}
+            >
+              {t("sagi.bubbleOpen")}
+            </button>
+          )}
+        </div>
+      )}
     </div>
   );
 }

client/src/components/Sagi/__tests__/PetChat.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @file PetChat.test.ts
+ * @description Unit tests for the pet chat's transcript-to-bubbles folding (`chatLines`).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { describe, it, expect } from "vitest";
+import { chatLines } from "../PetChat";
+import type { TranscriptMessage } from "../../../lib/types";
+
+const msg = (m: Partial<TranscriptMessage>): TranscriptMessage =>
+  ({ type: "user", timestamp: null, content: [], ...m }) as TranscriptMessage;
+
+describe("chatLines", () => {
+  it("keeps the user's words and the assistant's prose, folding tool calls into one chip", () => {
+    const lines = chatLines([
+      msg({ type: "user", sender: "user", content: [{ type: "text", text: "hi" }] }),
+      msg({
+        type: "assistant",
+        content: [
+          { type: "thinking", text: "hmm" },
+          { type: "tool_use", name: "Read" },
+        ],
+      }),
+      msg({ type: "user", sender: "tool", content: [{ type: "tool_result", output: "x" }] }),
+      msg({
+        type: "assistant",
+        content: [
+          { type: "tool_use", name: "Read" },
+          { type: "text", text: "hello!" },
+        ],
+      }),
+    ]);
+    expect(lines.map((l) => (l.role === "tools" ? l.names : l.text))).toEqual([
+      "hi",
+      ["Read", "Read"],
+      "hello!",
+    ]);
+  });
+
+  it("drops Claude Code's own injected lines", () => {
+    const lines = chatLines([
+      msg({ sender: "user", content: [{ type: "text", text: "<command-name>/clear</command-name>" }] }),
+    ]);
+    expect(lines).toEqual([]);
+  });
+});

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

@@ -261,7 +261,7 @@ describe("PetMenu", () => {
     renderMenu();
     fireEvent.click(screen.getByTestId("pet-choose"));
     fireEvent.click(await screen.findByTestId("pet-featured-goku"));
-    await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "cp-goku", kind: "codex" }));
+    await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "cp-goku", kind: "codex", name: "Goku" }));
     expect(api.pets.installFeatured).toHaveBeenCalledWith("goku");
   });
 
@@ -284,7 +284,7 @@ describe("PetMenu", () => {
     });
     fireEvent.change(screen.getByTestId("pet-image-input"), { target: { files: [file] } });
     await waitFor(() =>
-      expect(sagiPrefs.getPet()).toEqual({ id: "p-bbbbbbbbbbbb", kind: "image" })
+      expect(sagiPrefs.getPet()).toEqual({ id: "p-bbbbbbbbbbbb", kind: "image", name: "Dog" })
     );
     expect(api.pets.upload).toHaveBeenCalledWith(file);
   });
@@ -313,11 +313,11 @@ describe("PetSettings", () => {
   it("downloads a featured pet on its first pick, wears an own one, deletes it back to Sagi", async () => {
     render(<PetSettings />);
     fireEvent.click(await screen.findByTestId("pet-card-featured-goku"));
-    await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "cp-goku", kind: "codex" }));
+    await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "cp-goku", kind: "codex", name: "Goku" }));
     expect(api.pets.installFeatured).toHaveBeenCalledWith("goku");
 
     fireEvent.click(screen.getByTestId("pet-card-own-p-aaaaaaaaaaaa"));
-    expect(sagiPrefs.getPet()).toEqual({ id: "p-aaaaaaaaaaaa", kind: "image" });
+    expect(sagiPrefs.getPet()).toEqual({ id: "p-aaaaaaaaaaaa", kind: "image", name: "My cat" });
     fireEvent.click(screen.getByTestId("pet-card-own-p-aaaaaaaaaaaa-delete"));
     answerConfirm(true);
     await waitFor(() => expect(sagiPrefs.getPet()).toEqual({ id: "sagi" }));
@@ -329,7 +329,7 @@ describe("PetSettings", () => {
     const file = new File([new Uint8Array([0x89, 0x50])], "Dog.png", { type: "image/png" });
     fireEvent.change(screen.getByTestId("pet-settings-image-input"), { target: { files: [file] } });
     await waitFor(() =>
-      expect(sagiPrefs.getPet()).toEqual({ id: "p-bbbbbbbbbbbb", kind: "image" })
+      expect(sagiPrefs.getPet()).toEqual({ id: "p-bbbbbbbbbbbb", kind: "image", name: "Dog" })
     );
   });
 

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

@@ -1,6 +1,6 @@
 /**
  * @file Sagi.test.tsx
- * @description Render tests for the Sagi companion component — mounting, mood rendering, the ⌘B panel toggle, and accessibility attributes.
+ * @description Render tests for the Sagi companion component — mounting, mood rendering, the ⌘B chat toggle (the chat window is the pet's whole UI: status strip, local answers, New chat stopping the old session), and accessibility attributes.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
@@ -18,6 +18,7 @@ import { useSagiPosition } from "../useSagiPosition";
 import { MemoryRouter } from "react-router-dom";
 import { Sagi } from "../Sagi";
 import { eventBus } from "../../../lib/eventBus";
+import { api } from "../../../lib/api";
 import type { WSMessage, Session } from "../../../lib/types";
 
 function renderSagi() {
@@ -54,13 +55,13 @@ describe("Sagi widget", () => {
     expect(screen.getByRole("img", { name: /sagi/i })).toBeInTheDocument();
   });
 
-  it("opens the panel on click and answers a local status question", () => {
+  it("opens the chat on click and answers a local status question there", () => {
     renderSagi();
     fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
-    const panel = screen.getByRole("dialog", { name: /sagi companion/i });
+    const panel = screen.getByRole("dialog", { name: /chat with sagi/i });
     expect(panel).toBeInTheDocument();
 
-    const input = within(panel).getByLabelText(/ask sagi/i);
+    const input = within(panel).getByLabelText(/ask sagi anything/i);
     fireEvent.change(input, { target: { value: "status" } });
     fireEvent.submit(input.closest("form")!);
     expect(within(panel).getByText(/live ·/i)).toBeInTheDocument();
@@ -88,16 +89,114 @@ describe("Sagi widget", () => {
     expect(within(btn).getByText("1")).toBeInTheDocument();
   });
 
-  it("reflects the live count in the panel status", () => {
+  it("names the errored session in its bubble and in the chat", () => {
+    renderSagi();
+    act(() => {
+      eventBus.publish({
+        type: "session_updated",
+        data: { id: "a", status: "error", name: "Fix login", cwd: "/w/app", lane_id: 3 } as Session,
+        timestamp: "t",
+      });
+    });
+    const bubble = screen.getByRole("status");
+    expect(within(bubble).getByText("Fix login")).toBeInTheDocument();
+    expect(within(bubble).getByRole("button", { name: "Open" })).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    const panel = screen.getByRole("dialog", { name: /chat with sagi/i });
+    expect(within(panel).getByText("Needs you")).toBeInTheDocument();
+    expect(within(panel).getByRole("button", { name: /Fix login/ })).toBeInTheDocument();
+  });
+
+  it("stays quiet about a cleared error when that session updates again", () => {
+    renderSagi();
+    act(() => {
+      eventBus.publish(sessionMsg("a", "error"));
+    });
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    fireEvent.click(screen.getByRole("button", { name: "Clear alerts" }));
+    act(() => {
+      eventBus.publish(sessionMsg("a", "error"));
+    });
+    const btn = screen.getByRole("button", { name: /close sagi/i, expanded: true });
+    expect(within(btn).queryByText("1")).not.toBeInTheDocument();
+    expect(JSON.parse(localStorage.getItem("agenthub.pet.dismissedErrors")!)).toEqual(["a"]);
+  });
+
+  it("renames the pet from the chat header", () => {
+    renderSagi();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    fireEvent.click(screen.getByRole("button", { name: /rename sagi/i }));
+    const input = screen.getByLabelText("Pet name");
+    fireEvent.change(input, { target: { value: "Mochi" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(screen.getByRole("dialog", { name: /chat with mochi/i })).toBeInTheDocument();
+    expect(screen.getByLabelText(/ask mochi anything/i)).toBeInTheDocument();
+  });
+
+  it("hands a question it cannot answer to the AI", () => {
+    localStorage.setItem("agenthub.defaultTool", "claude");
+    const ensure = vi.spyOn(api.lanes, "ensure").mockReturnValue(new Promise(() => {}));
+    renderSagi();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    const chat = screen.getByRole("dialog", { name: /chat with sagi/i });
+    const input = within(chat).getByLabelText(/ask sagi anything/i);
+    fireEvent.change(input, { target: { value: "write me a haiku" } });
+    fireEvent.submit(input.closest("form")!);
+    expect(within(chat).getByText("write me a haiku")).toBeInTheDocument();
+    expect(ensure).toHaveBeenCalledWith({ title: "Sagi" });
+    ensure.mockRestore();
+  });
+
+  it("reopens the remembered chat, and New chat stops its session", async () => {
+    localStorage.setItem(
+      "agenthub.pet.chat",
+      JSON.stringify({ laneId: 7, runId: "agenthub-lane-7-1", tool: "claude" })
+    );
+    const get = vi
+      .spyOn(api.run, "get")
+      .mockReturnValue(new Promise(() => {}) as ReturnType<typeof api.run.get>);
+    const kill = vi.spyOn(api.run, "kill").mockResolvedValue({ ok: true });
+    renderSagi();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    expect(screen.getByRole("button", { name: /open in workspace/i })).toBeInTheDocument();
+    await act(async () => {
+      fireEvent.click(screen.getByRole("button", { name: /new chat/i }));
+    });
+    expect(kill).toHaveBeenCalledWith("agenthub-lane-7-1", { archive: true });
+    expect(localStorage.getItem("agenthub.pet.chat")).toBeNull();
+    expect(screen.queryByRole("button", { name: /open in workspace/i })).not.toBeInTheDocument();
+    get.mockRestore();
+    kill.mockRestore();
+  });
+
+  it("a pat shows its reaction on the pet even while the chat is open", () => {
+    renderSagi();
+    fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
+    fireEvent.click(screen.getByRole("button", { name: /pat sagi/i }));
+    const pet = screen.getByRole("button", { name: /close sagi/i, expanded: true });
+    expect(pet.querySelector(".sagi-reaction-text")?.textContent).toBeTruthy();
+  });
+
+  it("stroking the pet back and forth pats it", () => {
+    renderSagi();
+    const pet = screen.getByRole("button", { name: /open sagi companion/i });
+    const xs = [100, 130, 100, 130, 100, 130, 100];
+    act(() => {
+      for (const x of xs) fireEvent.pointerMove(pet, { clientX: x, clientY: 50, buttons: 0 });
+    });
+    expect(pet.querySelector(".sagi-reaction-text")).not.toBeNull();
+  });
+
+  it("reflects the live count in the chat status", () => {
     renderSagi();
     act(() => {
       eventBus.publish(sessionMsg("a", "active"));
       eventBus.publish(sessionMsg("b", "active"));
     });
     fireEvent.click(screen.getByRole("button", { name: /open sagi companion/i }));
-    const panel = screen.getByRole("dialog", { name: /sagi companion/i });
+    const panel = screen.getByRole("dialog", { name: /chat with sagi/i });
     // The "live" stat chip shows value 2 next to its label.
-    const liveChip = within(panel).getByText("live").closest("div")!;
+    const liveChip = within(panel).getByText("live").closest("span.rounded-full")! as HTMLElement;
     expect(within(liveChip).getByText("2")).toBeInTheDocument();
   });
 
@@ -107,7 +206,7 @@ describe("Sagi widget", () => {
     expect(screen.queryByRole("button", { name: /open sagi companion/i })).not.toBeInTheDocument();
   });
 
-  it("a tap (no movement) still opens the panel", () => {
+  it("a tap (no movement) still opens the chat", () => {
     renderSagi();
     const btn = screen.getByRole("button", { name: /open sagi companion/i });
     act(() => {
@@ -115,7 +214,7 @@ describe("Sagi widget", () => {
       fireEvent.pointerUp(btn, { clientX: 990, clientY: 700 });
     });
     fireEvent.click(btn);
-    expect(screen.getByRole("dialog", { name: /sagi companion/i })).toBeInTheDocument();
+    expect(screen.getByRole("dialog", { name: /chat with sagi/i })).toBeInTheDocument();
   });
 
   it("dragging snaps to an edge, persists position, and does not open the panel", () => {
@@ -144,7 +243,7 @@ describe("Sagi widget", () => {
       fireEvent.pointerUp(btn, { clientX: 992, clientY: 701 });
     });
     fireEvent.click(btn);
-    expect(screen.getByRole("dialog", { name: /sagi companion/i })).toBeInTheDocument();
+    expect(screen.getByRole("dialog", { name: /chat with sagi/i })).toBeInTheDocument();
     // No position was persisted because no real drag happened.
     expect(localStorage.getItem("agent-dashboard-sagi-pos")).toBeNull();
   });

client/src/components/Sagi/__tests__/brain.test.ts

@@ -225,6 +225,43 @@ describe("clearErrors", () => {
     expect(statusOf(s).liveCount).toBe(1);
     expect(s.worriedUntil).toBe(0);
   });
+
+  it("keeps a cleared session quiet while it stays errored", () => {
+    let s = initialSagiState(T0);
+    ({ state: s } = reduceSagi(s, sessionMsg("b", "error"), T0));
+    s = clearErrors(s);
+    const again = reduceSagi(s, sessionMsg("b", "error", T0 + 1), T0 + 1);
+    expect(again.pulse).toBeNull();
+    expect(statusOf(again.state).errorCount).toBe(0);
+    expect(again.state.worriedUntil).toBe(0);
+    const ev = reduceSagi(
+      again.state,
+      { type: "new_event", data: { session_id: "b", event_type: "toolError" }, timestamp: "" } as WSMessage,
+      T0 + 2
+    );
+    expect(ev.pulse).toBeNull();
+    expect(seedSessions(s, [{ id: "b", status: "error" }], T0).sessions.b).toBeUndefined();
+  });
+
+  it("alerts again once a cleared session recovers and fails anew", () => {
+    let s = initialSagiState(T0);
+    ({ state: s } = reduceSagi(s, sessionMsg("b", "error"), T0));
+    s = clearErrors(s);
+    ({ state: s } = reduceSagi(s, sessionMsg("b", "active"), T0));
+    expect(s.dismissed).not.toHaveProperty("b");
+    const r = reduceSagi(s, sessionMsg("b", "error"), T0);
+    expect(r.pulse).toBe("error");
+  });
+});
+
+describe("error alerts fire on the transition only", () => {
+  it("does not re-alert on each update of a still-errored session", () => {
+    let s = initialSagiState(T0);
+    ({ state: s } = reduceSagi(s, sessionMsg("a", "error"), T0));
+    const r = reduceSagi(s, sessionMsg("a", "error"), T0 + 10_000);
+    expect(r.pulse).toBeNull();
+    expect(statusOf(r.state).errorCount).toBe(1);
+  });
 });
 
 // Reference the imported constant so it is exercised and tsc-clean.

client/src/components/Sagi/__tests__/intents.test.ts

@@ -75,4 +75,27 @@ describe("matchIntent", () => {
     const r = matchIntent("Refactor my auth module", status());
     expect(r).toEqual({ kind: "handoff", prompt: "Refactor my auth module" });
   });
+
+  it("understands Vietnamese keywords", () => {
+    const r = matchIntent("có lỗi nào không?", status({ errorCount: 2 }));
+    if (r.kind === "answer") expect(r.text).toContain("2 sessions errored");
+    expect(matchIntent("đang chạy gì vậy", status({ liveCount: 1 })).kind).toBe("answer");
+    expect(matchIntent("tình hình sao rồi", status()).kind).toBe("answer");
+  });
+
+  it("names the sessions it reports when it knows them", () => {
+    const r = matchIntent("any errors?", status({ errorCount: 1 }), {
+      attention: [{ id: "a", kind: "error", name: "Fix login", cwd: null, lane_id: null }],
+    });
+    if (r.kind === "answer") expect(r.text).toContain("errored: Fix login");
+  });
+
+  it("introduces itself by the pet's name and reacts to a pat", () => {
+    const who = matchIntent("who are you", status(), { name: "Mochi" });
+    expect(who).toMatchObject({ kind: "answer", moment: "wave" });
+    if (who.kind === "answer") expect(who.text).toContain("Mochi");
+    expect(matchIntent("pat", status())).toMatchObject({ kind: "answer", moment: "jump" });
+    // "pat" inside another word is not a pat.
+    expect(matchIntent("update the path", status()).kind).toBe("handoff");
+  });
 });

client/src/components/Sagi/brain.ts

@@ -137,14 +137,7 @@ import type { WSMessage, Session, Agent, RunStatusPayload, DashboardEvent } from
 
 /** All moods Sagi can express, highest priority first (see `deriveMood`). */
 export type Mood =
-  | "disconnected"
-  | "worried"
-  | "stuck"
-  | "happy"
-  | "thinking"
-  | "watching"
-  | "sleeping"
-  | "idle";
+  "disconnected" | "worried" | "stuck" | "happy" | "thinking" | "watching" | "sleeping" | "idle";
 
 /**
  * A one-shot signal describing what just happened, emitted by `reduceSagi`.
@@ -152,13 +145,21 @@ export type Mood =
  * was irrelevant or non-notable.
  */
 export type SagiPulse =
-  | "session_done"
-  | "session_start"
-  | "subagent_spawn"
-  | "waiting"
-  | "error"
-  | "run_done"
-  | null;
+  "session_done" | "session_start" | "subagent_spawn" | "waiting" | "error" | "run_done" | null;
+
+/** A short animation the pet plays on an event or a pat, over its mood. */
+export type PetMoment = "wave" | "jump" | "fail" | "wait" | "review";
+
+/** Which moment each pulse plays: greet a new session, hop at a finish,
+ *  inspect a new subagent, tap a foot while you are awaited, flinch at an error. */
+export const MOMENT_OF_PULSE: Record<NonNullable<SagiPulse>, PetMoment> = {
+  session_start: "wave",
+  session_done: "jump",
+  run_done: "jump",
+  subagent_spawn: "review",
+  waiting: "wait",
+  error: "fail",
+};
 
 export interface SagiStatus {
   /** Active + waiting sessions (everything not finished/errored). */
@@ -182,6 +183,47 @@ export interface SagiState {
   worriedUntil: number;
   /** True while an Ask request is in flight (panel). */
   thinking: boolean;
+  /** Errored sessions the user cleared ("clear alerts"). Their further
+   *  updates, agent errors and failure events stay silent until the session
+   *  goes active again or ends — otherwise every update of a still-errored
+   *  session re-raised the alert the user had just dismissed. */
+  dismissed: Record<string, true>;
+  /** Name and owning workspace of each tracked session, so a bubble or the
+   *  panel can say WHICH session it means and open it. */
+  info: Record<string, SessionInfo>;
+}
+
+/** What Sagi knows about a session beyond its status. */
+export interface SessionInfo {
+  name: string | null;
+  cwd: string | null;
+  lane_id: number | null;
+}
+
+/** The session a pulse is about, when it is about one. */
+export interface SagiSubject extends SessionInfo {
+  id: string;
+}
+
+/** A session that needs the user: errored, or waiting on their input. */
+export interface AttentionItem extends SagiSubject {
+  kind: "error" | "waiting";
+}
+
+const infoOf = (s: {
+  name?: string | null;
+  cwd?: string | null;
+  lane_id?: number | null;
+}): SessionInfo => ({ name: s.name ?? null, cwd: s.cwd ?? null, lane_id: s.lane_id ?? null });
+
+/** A session's label for a bubble: its name, else its folder, else a short id. */
+export function subjectLabel(s: SagiSubject): string {
+  if (s.name && s.name.trim()) return s.name.trim();
+  const base = s.cwd
+    ?.replace(/[\\/]+$/, "")
+    .split(/[\\/]/)
+    .pop();
+  return base || s.id.slice(0, 8);
 }
 
 // Tunable timing constants (ms).
@@ -211,6 +253,8 @@ export function initialSagiState(now: number): SagiState {
     happyUntil: 0,
     worriedUntil: 0,
     thinking: false,
+    dismissed: {},
+    info: {},
   };
 }
 
@@ -256,16 +300,28 @@ export function reduceSagi(
   state: SagiState,
   msg: WSMessage,
   now: number
-): { state: SagiState; pulse: SagiPulse } {
+): { state: SagiState; pulse: SagiPulse; subject?: SagiSubject } {
+  // The tracked session an agent/event message belongs to, when known.
+  const known = (id: string | undefined): SagiSubject | undefined =>
+    id ? { id, ...(state.info[id] ?? { name: null, cwd: null, lane_id: null }) } : undefined;
   switch (msg.type) {
     case "session_created":
     case "session_updated": {
       const s = msg.data as Session;
       if (!s || !s.id) return { state, pulse: null };
       const sessions = { ...state.sessions };
+      const info = { ...state.info, [s.id]: infoOf(s) };
+      const subject: SagiSubject = { id: s.id, ...info[s.id]! };
+      let dismissed = state.dismissed;
       let pulse: SagiPulse = null;
       let happyUntil = state.happyUntil;
       let worriedUntil = state.worriedUntil;
+      // Anything but a (still) errored status ends a dismissal: a later error
+      // of that session is a new one and must alert again.
+      if (s.status !== "error" && s.id in dismissed) {
+        dismissed = { ...dismissed };
+        delete dismissed[s.id];
+      }
 
       if (s.status === "active") {
         // "waiting" = active session blocked on user input (permission prompt
@@ -280,12 +336,20 @@ export function reduceSagi(
           if (prev === undefined) pulse = "session_start";
         }
       } else if (s.status === "error") {
+        if (s.id in dismissed) {
+          return { state: { ...state, lastActivityAt: now }, pulse: null };
+        }
+        // Alert on the transition INTO error only; a session that stays
+        // errored keeps getting updates and must not re-alert on each one.
+        if (sessions[s.id] !== "error") {
+          worriedUntil = now + WORRIED_MS;
+          pulse = "error";
+        }
         sessions[s.id] = "error";
-        worriedUntil = now + WORRIED_MS;
-        pulse = "error";
       } else if (s.status === "completed" || s.status === "abandoned") {
         const wasTracked = s.id in sessions;
         delete sessions[s.id];
+        delete info[s.id];
         if (s.status === "completed") {
           happyUntil = now + HAPPY_MS;
           if (wasTracked) pulse = "session_done";
@@ -293,31 +357,46 @@ export function reduceSagi(
       }
 
       return {
-        state: { ...state, sessions, happyUntil, worriedUntil, lastActivityAt: now },
+        state: {
+          ...state,
+          sessions,
+          dismissed,
+          info,
+          happyUntil,
+          worriedUntil,
+          lastActivityAt: now,
+        },
         pulse,
+        subject,
       };
     }
 
     case "agent_created": {
       const a = msg.data as Agent;
-      if (a && a.status === "error") {
+      if (a && a.status === "error" && !(a.session_id in state.dismissed)) {
         return {
           state: { ...state, worriedUntil: now + WORRIED_MS, lastActivityAt: now },
           pulse: "error",
+          subject: known(a.session_id),
         };
       }
       // A freshly spawned subagent is worth announcing; the main agent landing
       // is already covered by session_start.
       const pulse: SagiPulse = a && a.type === "subagent" ? "subagent_spawn" : null;
-      return { state: { ...state, lastActivityAt: now }, pulse };
+      return {
+        state: { ...state, lastActivityAt: now },
+        pulse,
+        subject: pulse ? known(a.session_id) : undefined,
+      };
     }
 
     case "agent_updated": {
       const a = msg.data as Agent;
-      if (a && a.status === "error") {
+      if (a && a.status === "error" && !(a.session_id in state.dismissed)) {
         return {
           state: { ...state, worriedUntil: now + WORRIED_MS, lastActivityAt: now },
           pulse: "error",
+          subject: known(a.session_id),
         };
       }
       return { state: { ...state, lastActivityAt: now }, pulse: null };
@@ -325,7 +404,8 @@ export function reduceSagi(
 
     case "new_event": {
       const e = msg.data as DashboardEvent;
-      const isFailure = !!e && FAILURE_EVENT_TYPES.has(e.event_type);
+      const isFailure =
+        !!e && FAILURE_EVENT_TYPES.has(e.event_type) && !(e.session_id in state.dismissed);
       return {
         state: {
           ...state,
@@ -333,6 +413,7 @@ export function reduceSagi(
           worriedUntil: isFailure ? now + WORRIED_MS : state.worriedUntil,
         },
         pulse: isFailure ? "error" : null,
+        subject: isFailure ? known(e.session_id) : undefined,
       };
     }
 
@@ -361,24 +442,60 @@ export function reduceSagi(
  */
 export function seedSessions(
   state: SagiState,
-  rows: ReadonlyArray<{ id: string; status: string; awaiting_input_since?: string | null }>,
+  rows: ReadonlyArray<{
+    id: string;
+    status: string;
+    awaiting_input_since?: string | null;
+    name?: string | null;
+    cwd?: string | null;
+    lane_id?: number | null;
+  }>,
   now: number
 ): SagiState {
   const sessions = { ...state.sessions };
+  const info = { ...state.info };
   for (const r of rows) {
     if (!r || !r.id) continue;
-    if (r.status === "error") sessions[r.id] = "error";
-    else if (r.status === "active") sessions[r.id] = r.awaiting_input_since ? "waiting" : "active";
-    // completed / abandoned: leave untracked.
+    if (r.status === "error") {
+      if (r.id in state.dismissed) continue;
+      sessions[r.id] = "error";
+    } else if (r.status === "active") {
+      sessions[r.id] = r.awaiting_input_since ? "waiting" : "active";
+    } else continue; // completed / abandoned: leave untracked.
+    info[r.id] = infoOf(r);
   }
-  return { ...state, sessions, lastActivityAt: now };
+  return { ...state, sessions, info, lastActivityAt: now };
 }
 
-/** Drop all errored sessions from tracking (used by "clear alerts"). */
+/** Errored sessions first, then the ones waiting on the user — the panel's list. */
+export function attentionOf(state: SagiState): AttentionItem[] {
+  const out: AttentionItem[] = [];
+  for (const kind of ["error", "waiting"] as const) {
+    for (const [id, s] of Object.entries(state.sessions)) {
+      if (s !== kind) continue;
+      out.push({
+        id,
+        kind,
+        ...(state.info[id] ?? { name: null, cwd: null, lane_id: null }),
+      });
+    }
+  }
+  return out;
+}
+
+/** Drop all errored sessions from tracking (used by "clear alerts") and
+ *  remember them as dismissed, so their next update does not bring the alert
+ *  straight back. */
 export function clearErrors(state: SagiState): SagiState {
   const sessions: SagiState["sessions"] = {};
+  const dismissed = { ...state.dismissed };
+  const info = { ...state.info };
   for (const [id, s] of Object.entries(state.sessions)) {
     if (s !== "error") sessions[id] = s;
+    else {
+      dismissed[id] = true;
+      delete info[id];
+    }
   }
-  return { ...state, sessions, worriedUntil: 0 };
+  return { ...state, sessions, dismissed, info, worriedUntil: 0 };
 }

client/src/components/Sagi/intents.ts

@@ -3,7 +3,9 @@
  * @description Sagi's local "Ask" brain. Matches a free-text question against a
  *   small set of intents answerable from cached dashboard status. Anything it
  *   can't answer becomes a handoff to the Run page (spawn a real `claude`).
- *   Pure function - no network, no DOM - so it's fully unit-testable.
+ *   Understands English and Vietnamese keywords, names the sessions it reports
+ *   when it knows them, and answers in the UI language (`settings:sagi.intent`).
+ *   No network, no DOM - so it's fully unit-testable.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 /* =============================================================================
@@ -28,6 +30,8 @@
  *
  * ## Public surface
  * - `AskResult` — exported API; see TSDoc on the symbol for behavior.
+ * - `AskContext` — exported API; see TSDoc on the symbol for behavior.
+ * - `statusSummary` — exported API; see TSDoc on the symbol for behavior.
  * - `matchIntent` — exported API; see TSDoc on the symbol for behavior.
  *
  * ## Testing pointers
@@ -54,70 +58,157 @@
  *
  * ----------------------------------------------------------------------------- */
 
-import type { SagiStatus } from "./brain";
+import i18n from "../../i18n";
+import { subjectLabel, type AttentionItem, type PetMoment, type SagiStatus } from "./brain";
+import { pickLine } from "./quips";
 
-export type AskResult = { kind: "answer"; text: string } | { kind: "handoff"; prompt: string };
+export type AskResult =
+  { kind: "answer"; text: string; moment?: PetMoment } | { kind: "handoff"; prompt: string };
 
-const plural = (n: number) => (n === 1 ? "" : "s");
+/** What the answer may mention beyond the counts. */
+export interface AskContext {
+  /** The pet's shown name. */
+  name?: string;
+  /** Errored and waiting sessions, named (`attentionOf`). */
+  attention?: ReadonlyArray<AttentionItem>;
+}
 
-export function matchIntent(query: string, status: SagiStatus): AskResult {
-  const q = query.trim().toLowerCase();
-  if (!q) {
-    return {
-      kind: "answer",
-      text: "ask me about your sessions - what's running, any errors, or a quick status.",
-    };
-  }
+const t = (key: string, vars?: Record<string, unknown>) =>
+  i18n.t(`settings:sagi.intent.${key}`, vars ?? {});
+
+/** ": a, b, c" for up to three named sessions of a kind, "" when none known. */
+function listOf(items: ReadonlyArray<AttentionItem> | undefined, kind: AttentionItem["kind"]) {
+  const names = (items ?? []).filter((i) => i.kind === kind).map(subjectLabel);
+  if (names.length === 0) return "";
+  const shown = names.slice(0, 3).join(", ");
+  return `: ${names.length > 3 ? `${shown}…` : shown}`;
+}
+
+/** "2 sessions live, 1 waiting on you" — the one-line status a greeting carries. */
+export function statusSummary(status: SagiStatus): string {
+  const parts = [i18n.t("settings:sagi.greet.summary", { count: status.liveCount })];
+  if (status.waitingCount > 0)
+    parts.push(i18n.t("settings:sagi.greet.summaryWaiting", { count: status.waitingCount }));
+  if (status.errorCount > 0)
+    parts.push(i18n.t("settings:sagi.greet.summaryErrors", { count: status.errorCount }));
+  return parts.join(", ");
+}
+
+export function matchIntent(query: string, status: SagiStatus, ctx: AskContext = {}): AskResult {
+  const q = query.trim().toLowerCase().normalize("NFC");
+  const name = ctx.name || "Sagi";
+  if (!q) return { kind: "answer", text: t("empty") };
 
   const has = (...words: string[]) => words.some((w) => q.includes(w));
+  // Whole-word match, for short words that hide inside longer ones ("hi" in "this").
+  const word = (...words: string[]) =>
+    words.some((w) => new RegExp(`(^|[^\\p{L}])${w}($|[^\\p{L}])`, "u").test(q));
 
-  if (has("help", "what can you", "what do you do")) {
-    return {
-      kind: "answer",
-      text: 'I watch your sessions. Try "what\'s running", "any errors", or "status". Anything else, I\'ll hand to Claude.',
-    };
+  if (has("help", "what can you", "what do you do", "trợ giúp", "làm được gì", "hướng dẫn")) {
+    return { kind: "answer", text: t("help", { name }) };
+  }
+
+  if (has("who are you", "your name", "bạn là ai", "tên gì", "tên bạn", "là ai")) {
+    return { kind: "answer", text: t("whoami", { name }), moment: "wave" };
+  }
+
+  if (has("thank", "thx", "cảm ơn", "cám ơn") || word("ty", "tks")) {
+    return { kind: "answer", text: pickLine("intent.thanks"), moment: "jump" };
+  }
+
+  if (
+    has("good boy", "good girl", "cute", "ngoan", "dễ thương", "xoa đầu", "vuốt ve", "giỏi quá") ||
+    word("pat")
+  ) {
+    return { kind: "answer", text: pickLine("pat"), moment: "jump" };
   }
 
   // Errors first: "any failed runs" should report errors, not live count.
-  if (has("error", "broke", "broken", "fail", "wrong", "crash")) {
+  if (
+    has("error", "broke", "broken", "fail", "wrong", "crash", "lỗi", "hỏng", "thất bại", "sự cố")
+  ) {
     return {
       kind: "answer",
       text:
         status.errorCount > 0
-          ? `${status.errorCount} session${plural(status.errorCount)} errored - open the panel to jump to them.`
-          : "no errors - all clean 🐾",
+          ? t("errors", { count: status.errorCount, list: listOf(ctx.attention, "error") })
+          : t("errorsNone"),
     };
   }
 
-  if (has("waiting", "stuck", "blocked", "input", "my turn", "paused")) {
+  if (
+    has(
+      "waiting",
+      "stuck",
+      "blocked",
+      "input",
+      "my turn",
+      "paused",
+      "chờ",
+      "đợi",
+      "kẹt",
+      "tới lượt",
+      "đến lượt"
+    )
+  ) {
     return {
       kind: "answer",
       text:
         status.waitingCount > 0
-          ? `${status.waitingCount} session${plural(status.waitingCount)} waiting on you 👀`
-          : "nothing's waiting on you right now 🐾",
+          ? t("waiting", { count: status.waitingCount, list: listOf(ctx.attention, "waiting") })
+          : t("waitingNone"),
     };
   }
 
-  if (has("running", "active", "live", "going on", "happening", "in progress")) {
-    const tail = status.waitingCount > 0 ? ` (${status.waitingCount} waiting on you 👀)` : "";
+  if (
+    has(
+      "running",
+      "active",
+      "live",
+      "going on",
+      "happening",
+      "in progress",
+      "đang chạy",
+      "đang làm",
+      "hoạt động"
+    )
+  ) {
+    const tail = status.waitingCount > 0 ? t("liveTail", { count: status.waitingCount }) : "";
     return {
       kind: "answer",
-      text:
-        status.liveCount > 0
-          ? `${status.liveCount} session${plural(status.liveCount)} live right now 🐾${tail}`
-          : "nothing's running right now - all quiet.",
+      text: status.liveCount > 0 ? t("live", { count: status.liveCount, tail }) : t("liveNone"),
     };
   }
 
-  if (has("status", "summary", "overview", "how are things", "how's it", "how is it")) {
+  if (
+    has(
+      "status",
+      "summary",
+      "overview",
+      "how are things",
+      "how's it",
+      "how is it",
+      "tình hình",
+      "trạng thái",
+      "tổng quan",
+      "thế nào",
+      "sao rồi"
+    )
+  ) {
     return {
       kind: "answer",
-      text: `${status.liveCount} live · ${status.waitingCount} waiting · ${status.errorCount} errored · ${
-        status.connected ? "connected" : "offline"
-      }.`,
+      text: t("status", {
+        live: status.liveCount,
+        waiting: status.waitingCount,
+        errors: status.errorCount,
+        conn: t(status.connected ? "connected" : "offline"),
+      }),
     };
   }
 
+  if (word("hi", "hello", "hey", "yo", "chào", "xin chào", "alo")) {
+    return { kind: "answer", text: t("hello", { summary: statusSummary(status) }), moment: "wave" };
+  }
+
   return { kind: "handoff", prompt: query.trim() };
 }

client/src/components/Sagi/prefs.ts

@@ -56,12 +56,19 @@ const MUTED_KEY = "agent-dashboard-sagi-muted";
 const POS_KEY = "agent-dashboard-sagi-pos";
 const PET_KEY = "agenthub.pet";
 const SIZE_KEY = "agenthub.pet.size";
+const DISMISSED_KEY = "agenthub.pet.dismissedErrors";
+/** Per-pet nicknames the user typed, `{ [petId]: name }`. */
+const NAMES_KEY = "agenthub.pet.names";
+export const PET_NAME_MAX = 40;
+/** Most recent dismissed error sessions kept across reloads. */
+const DISMISSED_MAX = 200;
 /** Sagi's own size, and the slider's range. */
 export const PET_SIZE = { default: 68, min: 48, max: 250 };
 
 /** The pet the mascot wears: Sagi itself, or a custom one (`/api/pets`).
- *  The kind rides along so the mascot renders without a fetch. */
-export type PetChoice = { id: "sagi" } | { id: string; kind: "codex" | "image" };
+ *  The kind (and its display name) ride along so the mascot renders, and
+ *  introduces itself, without a fetch. */
+export type PetChoice = { id: "sagi" } | { id: string; kind: "codex" | "image"; name?: string };
 const SAGI: PetChoice = { id: "sagi" };
 
 function readPet(): PetChoice {
@@ -69,6 +76,7 @@ function readPet(): PetChoice {
     const p = JSON.parse(localStorage.getItem(PET_KEY) ?? "null") as Partial<{
       id: string;
       kind: string;
+      name: string;
     }> | null;
     if (
       p &&
@@ -76,13 +84,34 @@ function readPet(): PetChoice {
       p.id !== "sagi" &&
       (p.kind === "codex" || p.kind === "image")
     )
-      return { id: p.id, kind: p.kind };
+      return typeof p.name === "string" && p.name
+        ? { id: p.id, kind: p.kind, name: p.name.slice(0, PET_NAME_MAX) }
+        : { id: p.id, kind: p.kind };
   } catch {
     /* unreadable: Sagi */
   }
   return SAGI;
 }
 
+function readNames(): Record<string, string> {
+  try {
+    const raw = JSON.parse(localStorage.getItem(NAMES_KEY) ?? "{}") as unknown;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+    const out: Record<string, string> = {};
+    for (const [id, v] of Object.entries(raw)) if (typeof v === "string" && v) out[id] = v;
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/** The name the pet goes by: the user's nickname, else the pet's own, else Sagi. */
+export function petName(pet: PetChoice): string {
+  const nick = readNames()[pet.id];
+  if (nick) return nick;
+  return ("name" in pet && pet.name) || "Sagi";
+}
+
 function readSize(): number {
   const n = Number(localStorage.getItem(SIZE_KEY));
   return Number.isFinite(n) && n > 0
@@ -181,6 +210,37 @@ export const sagiPrefs = {
       SIZE_KEY,
       String(Math.round(Math.min(PET_SIZE.max, Math.max(PET_SIZE.min, px))))
     ),
+  /** Name a pet; an empty name gives it back its own. */
+  setNickname: (id: string, name: string) => {
+    const names = readNames();
+    const clean = name.replace(/\s+/g, " ").trim().slice(0, PET_NAME_MAX);
+    if (clean) names[id] = clean;
+    else delete names[id];
+    writeAndNotify(NAMES_KEY, JSON.stringify(names));
+  },
+  /** The user's nickname for a pet, "" when none. */
+  getNickname: (id: string) => readNames()[id] ?? "",
+  /** Errored session ids the user cleared, so a reload keeps them quiet. */
+  getDismissed: (): Record<string, true> => {
+    try {
+      const ids = JSON.parse(localStorage.getItem(DISMISSED_KEY) || "[]");
+      const out: Record<string, true> = {};
+      if (Array.isArray(ids)) for (const id of ids) if (typeof id === "string") out[id] = true;
+      return out;
+    } catch {
+      return {};
+    }
+  },
+  setDismissed: (dismissed: Record<string, true>) => {
+    try {
+      localStorage.setItem(
+        DISMISSED_KEY,
+        JSON.stringify(Object.keys(dismissed).slice(-DISMISSED_MAX))
+      );
+    } catch {
+      // Best-effort, like every pref here; no prefs event — widget-local state.
+    }
+  },
   /** Subscribe to any pref change; returns an unsubscribe fn. */
   subscribe(handler: () => void): () => void {
     const listener = () => handler();

client/src/components/Sagi/quips.ts

@@ -1,8 +1,8 @@
 /**
  * @file quips.ts
- * @description Sagi's personality: pools of short phrases keyed by pulse/mood,
- *   plus a deterministic-by-injection picker. Pure data + a pure function so it
- *   can be unit-tested without randomness leaking in.
+ * @description Sagi's personality: pools of short phrases keyed by pulse/mood
+ *   (and greetings, pat reactions), read from the `settings:sagi.*` i18n arrays
+ *   so they follow the UI language, plus a deterministic-by-injection picker.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 /* =============================================================================
@@ -24,10 +24,13 @@
  *
  * ## Internal dependencies
  * - `./brain`
+ * - `../../i18n`
  *
  * ## Public surface
  * - `QuipKey` — exported API; see TSDoc on the symbol for behavior.
  * - `pickQuip` — exported API; see TSDoc on the symbol for behavior.
+ * - `pickLine` — exported API; see TSDoc on the symbol for behavior.
+ * - `greetingKey` — exported API; see TSDoc on the symbol for behavior.
  * - `ALL_QUIP_KEYS` — exported API; see TSDoc on the symbol for behavior.
  *
  * ## Testing pointers
@@ -59,76 +62,60 @@
  *
  * ----------------------------------------------------------------------------- */
 
+import i18n from "../../i18n";
 import type { Mood, SagiPulse } from "./brain";
 
 export type QuipKey = NonNullable<SagiPulse> | Mood;
 
-const QUIPS: Record<QuipKey, string[]> = {
+export const ALL_QUIP_KEYS: QuipKey[] = [
   // Pulses (event-driven, transient bubbles)
-  session_done: [
-    "a session just wrapped up! 🐾",
-    "a session finished - nice work! ✨",
-    "that session's all done 😺",
-    "clean finish on that one 💜",
-  ],
-  session_start: [
-    "a new session started! 👀",
-    "a fresh session just landed 🐾",
-    "ooh, a new session to watch 😻",
-    "something new is cooking 🍲",
-  ],
-  subagent_spawn: [
-    "a subagent just spawned! 🐾",
-    "a little helper joined in 🤝",
-    "a subagent's on the job 🚀",
-    "reinforcements - new subagent! 😺",
-  ],
-  waiting: [
-    "a session needs your input 👀",
-    "a session is waiting on you ⏳",
-    "a session paused for your reply 💬",
-    "your turn - a session's waiting 🐾",
-  ],
-  error: [
-    "uh oh, a session hit an error 😿",
-    "something broke - wanna peek? 🙀",
-    "a hook tripped on something ⚠️",
-    "hiss… an error popped up 💢",
-  ],
-  run_done: [
-    "your run just finished! 🐾",
-    "the run's all wrapped up ✨",
-    "run complete - that's a wrap 😸",
-    "all done with that run 💜",
-  ],
-  // Moods (steady-state flavor, used by the panel / idle bubbles)
-  disconnected: [
-    "lost the connection… 😴",
-    "can't reach the server 📡",
-    "no signal - taking a nap 💤",
-  ],
-  worried: ["that didn't look right 😟", "keeping an eye out 👀", "hmm, something's off 🫣"],
-  stuck: [
-    "a session's been quiet a while… 🤔",
-    "is something stuck? ⏳",
-    "still chewing on it… 😾",
-  ],
-  happy: ["great run! 😻", "love a tidy finish ✨", "purrfect 💜"],
-  thinking: ["hmm, let me look… 🤔", "sniffing around… 🐾", "one sec, checking 🔍"],
-  watching: ["on the prowl 👀", "watching your sessions 😼", "eyes peeled 🐾"],
-  sleeping: ["zzz… 💤", "wake me if something happens 😴", "curled up, all calm 🐈"],
-  idle: ["all quiet 😺", "ready when you are 🐾", "just vibing ✨"],
-};
+  "session_done",
+  "session_start",
+  "subagent_spawn",
+  "waiting",
+  "error",
+  "run_done",
+  // Moods (steady-state flavor)
+  "disconnected",
+  "worried",
+  "stuck",
+  "happy",
+  "thinking",
+  "watching",
+  "sleeping",
+  "idle",
+];
+const KNOWN = new Set<string>(ALL_QUIP_KEYS);
 
 /**
- * Pick a quip for a key. `rand` is injectable for deterministic tests; defaults
- * to Math.random. Returns "" only for an unknown key (never throws).
+ * Pick one line from an i18n string array under `settings:sagi.<path>`.
+ * `rand` is injectable for deterministic tests. Returns "" for a missing or
+ * empty pool (never throws).
  */
-export function pickQuip(key: QuipKey, rand: () => number = Math.random): string {
-  const pool = QUIPS[key];
-  if (!pool || pool.length === 0) return "";
+export function pickLine(
+  path: string,
+  rand: () => number = Math.random,
+  vars?: Record<string, unknown>
+): string {
+  const pool = i18n.t(`settings:sagi.${path}`, { returnObjects: true, ...vars }) as unknown;
+  if (!Array.isArray(pool) || pool.length === 0) return "";
   const i = Math.min(pool.length - 1, Math.max(0, Math.floor(rand() * pool.length)));
-  return pool[i] ?? "";
+  const line = pool[i];
+  return typeof line === "string" ? line : "";
 }
 
-export const ALL_QUIP_KEYS = Object.keys(QUIPS) as QuipKey[];
+/**
+ * Pick a quip for a key, in the UI language. Returns "" only for an unknown
+ * key (never throws).
+ */
+export function pickQuip(key: QuipKey, rand: () => number = Math.random): string {
+  return KNOWN.has(key) ? pickLine(`quips.${key}`, rand) : "";
+}
+
+/** Which greeting pool fits the hour: morning 5–11, afternoon 12–17, evening 18–22, else night. */
+export function greetingKey(hour: number): "morning" | "afternoon" | "evening" | "night" {
+  if (hour >= 5 && hour < 12) return "morning";
+  if (hour >= 12 && hour < 18) return "afternoon";
+  if (hour >= 18 && hour < 23) return "evening";
+  return "night";
+}

client/src/components/Sagi/sagi.css

@@ -1,8 +1,12 @@
 /**
  * sagi.css - animations + mood expressions for the Sagi companion.
  * Colors mirror the app's theme tokens (accent #6366f1/#818cf8, surface scale)
- * with warm pink accents (ears, cheeks, nose) for cuteness. All continuous
- * motion is disabled under [data-reduced="1"] and prefers-reduced-motion.
+ * with warm pink accents (ears, cheeks, nose) for cuteness. No mood animates
+ * forever: each plays a few cycles when the mood begins and then rests — an
+ * infinite animation makes the browser draw a new frame 60 times a second for
+ * as long as the page is open (the drop-shadow filter re-rendered each time),
+ * which made the whole desktop stutter. All motion is disabled under
+ * [data-reduced="1"] and prefers-reduced-motion.
  * Transform origins are the delicate part - see the comments on .sagi-avatar
  * and .sagi-eye-blink for which reference box each one resolves against.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
@@ -206,20 +210,20 @@
 
 /* idle: gentle breathing + occasional blink */
 .sagi-avatar[data-mood="idle"] {
-  animation: sagi-breathe 4s ease-in-out infinite;
+  animation: sagi-breathe 4s ease-in-out 0s 3;
 }
 /* Blink lives on the inner group so it never overrides the outer group's
    eye-tracking translate (which would freeze the eyes - see the CSS-blink
    note in SagiAvatar.tsx). */
 .sagi-avatar[data-mood="idle"] .sagi-eye-blink {
-  animation: sagi-blink 5s ease-in-out infinite;
+  animation: sagi-blink 5s ease-in-out 0s 3;
 }
 /* happy: whole-mascot bob + twinkling sparkle */
 .sagi-avatar[data-mood="happy"] {
   animation: sagi-bob 0.5s ease-in-out 0s 4;
 }
 .sagi-avatar[data-mood="happy"] .sagi-sparkle {
-  animation: sagi-sparkle-twinkle 0.9s ease-in-out infinite;
+  animation: sagi-sparkle-twinkle 0.9s ease-in-out 0s 4;
   transform-origin: 797px 274px; /* sparkle centre, mascot 1050,380 */
 }
 /* worried: alarmed shake */
@@ -228,19 +232,97 @@
 }
 /* stuck: slow, drooping breathe (fatigued) */
 .sagi-avatar[data-mood="stuck"] {
-  animation: sagi-droop 2.4s ease-in-out infinite;
+  animation: sagi-droop 2.4s ease-in-out 0s 3;
 }
 /* thinking: rocking head tilt */
 .sagi-avatar[data-mood="thinking"] {
-  animation: sagi-rock 1.8s ease-in-out infinite;
+  animation: sagi-rock 1.8s ease-in-out 0s 4;
 }
 /* watching: attentive sway while a session is live */
 .sagi-avatar[data-mood="watching"] {
-  animation: sagi-sway 3.2s ease-in-out infinite;
+  animation: sagi-sway 3.2s ease-in-out 0s 3;
 }
 /* sleeping: slow breathe, droop */
 .sagi-avatar[data-mood="sleeping"] {
-  animation: sagi-breathe 5s ease-in-out infinite;
+  animation: sagi-breathe 5s ease-in-out 0s 3;
+}
+
+/* ── moments: one-shot reactions to an event or a pat (useSagiBrain), played
+   over the mood for ~2.4 s. Declared after the moods so they win the cascade.
+   Shared by Sagi's own art and an uploaded still image. ── */
+.sagi-avatar[data-moment="jump"],
+.sagi-pet-image[data-moment="jump"] {
+  animation: sagi-hop 0.6s cubic-bezier(0.3, 0, 0.4, 1) 0s 3;
+}
+.sagi-avatar[data-moment="wave"],
+.sagi-pet-image[data-moment="wave"] {
+  animation: sagi-wiggle 0.5s ease-in-out 0s 4;
+}
+.sagi-avatar[data-moment="fail"],
+.sagi-pet-image[data-moment="fail"] {
+  animation: sagi-shake 0.35s ease-in-out 0s 5;
+}
+.sagi-avatar[data-moment="wait"],
+.sagi-pet-image[data-moment="wait"] {
+  animation: sagi-tap 0.4s ease-in-out 0s 5;
+}
+.sagi-avatar[data-moment="review"],
+.sagi-pet-image[data-moment="review"] {
+  animation: sagi-peek 2.2s ease-in-out 0s 1;
+}
+.sagi-avatar[data-moment="jump"] .sagi-sparkle {
+  animation: sagi-sparkle-twinkle 0.9s ease-in-out 0s 4;
+  transform-origin: 797px 274px;
+}
+@keyframes sagi-hop {
+  0%,
+  100% {
+    transform: translateY(0) scale(1, 1);
+  }
+  15% {
+    transform: translateY(0) scale(1.08, 0.92);
+  }
+  45% {
+    transform: translateY(-14%) scale(0.96, 1.05);
+  }
+  75% {
+    transform: translateY(0) scale(1.04, 0.96);
+  }
+}
+@keyframes sagi-wiggle {
+  0%,
+  100% {
+    transform: rotate(0deg);
+  }
+  25% {
+    transform: rotate(-9deg);
+  }
+  75% {
+    transform: rotate(9deg);
+  }
+}
+@keyframes sagi-tap {
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-4%);
+  }
+}
+@keyframes sagi-peek {
+  0%,
+  100% {
+    transform: rotate(0deg) translateX(0);
+  }
+  25%,
+  40% {
+    transform: rotate(-7deg) translateX(-4%);
+  }
+  60%,
+  75% {
+    transform: rotate(7deg) translateX(4%);
+  }
 }
 
 /* ── reduced motion: kill all continuous animation ── */
@@ -339,7 +421,15 @@
   align-items: center;
   justify-content: center;
   border: 2px solid #0c0c14;
-  animation: sagi-error-pulse 1.2s ease-in-out infinite;
+  animation: sagi-error-pulse 1.2s ease-in-out 0s 5;
+}
+/* Sessions waiting on the user, when none errored: the same dot, amber. */
+.sagi-error-dot[data-kind="waiting"] {
+  background: #f59e0b;
+  animation: none;
+}
+.sagi-pet-image {
+  transform-origin: 50% 92%;
 }
 .sagi-bubble {
   max-width: 16rem;
@@ -356,6 +446,41 @@
 .sagi-bubble-enter {
   animation: sagi-bubble-in 0.22s ease-out;
 }
+.sagi-bubble[data-tone="error"] {
+  border-color: rgba(239, 68, 68, 0.6);
+}
+.sagi-bubble[data-tone="waiting"] {
+  border-color: rgba(245, 158, 11, 0.6);
+}
+/* The session(s) a bubble is about, and the button that opens it. */
+.sagi-bubble-detail {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+  font-size: 0.75rem;
+  line-height: 1rem;
+  color: #a8a8c0;
+}
+.sagi-bubble-subject {
+  min-width: 0;
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.sagi-bubble-open {
+  flex-shrink: 0;
+  padding: 0.125rem 0.5rem;
+  border-radius: 9999px;
+  background: rgba(139, 92, 246, 0.2);
+  color: #c4b5fd;
+  font-weight: 500;
+  transition: background 0.15s;
+}
+.sagi-bubble-open:hover {
+  background: rgba(139, 92, 246, 0.35);
+}
 @keyframes sagi-bubble-in {
   from {
     opacity: 0;
@@ -375,7 +500,7 @@
 /* An uploaded still image has no frames of its own: it bobs, faster while an
    agent works and slower asleep. A Codex spritesheet animates by its frames. */
 .sagi-pet-image {
-  animation: sagi-pet-bob 2.6s ease-in-out infinite;
+  animation: sagi-pet-bob 2.6s ease-in-out 0s 3;
   -webkit-user-drag: none;
 }
 .sagi-pet-image[data-mood="thinking"] {
@@ -403,3 +528,165 @@
 .sagi-flyout[data-front="1"] {
   z-index: 42;
 }
+
+/* ════════ the pet's chat window (PetChat.tsx) ════════ */
+
+/* The reference's soft gradient, in the theme's own accent rather than a fixed
+   colour: a tint of the accent at the top fading into the surface, so it
+   reads in every light and dark theme. Replies sit on the plain surface like
+   the reference's white bubbles; the user's own are accent-solid (white text
+   is only ever on accent-solid). */
+.pet-chat {
+  background: linear-gradient(
+    180deg,
+    color-mix(in srgb, rgb(var(--accent)) 22%, rgb(var(--surface-1))) 0%,
+    color-mix(in srgb, rgb(var(--accent)) 9%, rgb(var(--surface-1))) 45%,
+    rgb(var(--surface-1)) 100%
+  );
+}
+.pet-chat-head {
+  border-bottom: 1px solid color-mix(in srgb, rgb(var(--accent)) 18%, transparent);
+}
+.pet-chat-reply {
+  background: rgb(var(--surface-0));
+  border: 1px solid color-mix(in srgb, rgb(var(--accent)) 12%, transparent);
+}
+.pet-chat-tools {
+  background: color-mix(in srgb, rgb(var(--surface-0)) 70%, transparent);
+  border: 1px dashed color-mix(in srgb, rgb(var(--accent)) 25%, transparent);
+}
+.pet-chat-foot {
+  background: rgb(var(--surface-0));
+  border-top: 1px solid rgb(var(--border) / 0.6);
+}
+/* Three bouncing dots while a reply is written. */
+.pet-chat-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 9999px;
+  background: rgb(var(--accent));
+  opacity: 0.5;
+  animation: pet-chat-dot 1.2s ease-in-out infinite;
+}
+.pet-chat-dot:nth-child(2) {
+  animation-delay: 0.15s;
+}
+.pet-chat-dot:nth-child(3) {
+  animation-delay: 0.3s;
+}
+@keyframes pet-chat-dot {
+  0%,
+  60%,
+  100% {
+    transform: translateY(0);
+    opacity: 0.35;
+  }
+  30% {
+    transform: translateY(-4px);
+    opacity: 0.9;
+  }
+}
+/* The chat's terminal, attached but off-screen. It keeps a real size (so tmux
+   does not shrink the pane to fit it) and a non-zero box (so the paste
+   registry counts it as on screen). */
+.pet-chat-term {
+  position: fixed;
+  left: -10000px;
+  top: 0;
+  width: 760px;
+  height: 460px;
+  pointer-events: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .pet-chat-dot {
+    animation: none;
+  }
+}
+
+/* ════════ a pat's reaction, drawn on the pet itself ════════ */
+
+/* Hearts float up from the pet and its line shows beside it, inside the
+   avatar button — so a pat reads even while the panel or the chat is open
+   (the speech bubble hides then). */
+.sagi-reaction {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+.sagi-hearts {
+  position: absolute;
+  left: 50%;
+  top: 10%;
+  display: flex;
+  gap: 2px;
+  transform: translateX(-50%);
+  font-size: 14px;
+  line-height: 1;
+}
+.sagi-hearts > span {
+  animation: sagi-heart-up 1.6s ease-out forwards;
+  opacity: 0;
+}
+.sagi-hearts > span:nth-child(2) {
+  animation-delay: 0.15s;
+  font-size: 18px;
+}
+.sagi-hearts > span:nth-child(3) {
+  animation-delay: 0.3s;
+}
+@keyframes sagi-heart-up {
+  0% {
+    opacity: 0;
+    transform: translateY(6px) scale(0.6);
+  }
+  20% {
+    opacity: 1;
+    transform: translateY(-4px) scale(1);
+  }
+  100% {
+    opacity: 0;
+    transform: translateY(-34px) scale(0.9);
+  }
+}
+/* The line sits on the side away from the screen edge the pet docks to. */
+.sagi-reaction-text {
+  position: absolute;
+  top: 30%;
+  white-space: nowrap;
+  padding: 0.2rem 0.55rem;
+  border-radius: 9999px;
+  background: rgb(var(--surface-0));
+  border: 1px solid color-mix(in srgb, rgb(var(--accent)) 35%, transparent);
+  color: rgb(var(--fg-primary));
+  font-size: 0.75rem;
+  line-height: 1.1rem;
+  box-shadow: 0 4px 14px rgba(0, 0, 0, 0.18);
+  animation: sagi-reaction-in 2.4s ease-out forwards;
+}
+.sagi-reaction-text[data-side="right"] {
+  right: calc(100% + 6px);
+}
+.sagi-reaction-text[data-side="left"] {
+  left: calc(100% + 6px);
+}
+@keyframes sagi-reaction-in {
+  0% {
+    opacity: 0;
+    transform: scale(0.85);
+  }
+  10%,
+  80% {
+    opacity: 1;
+    transform: scale(1);
+  }
+  100% {
+    opacity: 0;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .sagi-hearts > span,
+  .sagi-reaction-text {
+    animation: none;
+    opacity: 1;
+  }
+}

client/src/components/Sagi/usePets.ts

@@ -47,7 +47,7 @@ export function usePets() {
     }
   };
 
-  const wear = (p: PetView) => sagiPrefs.setPet({ id: p.id, kind: p.kind });
+  const wear = (p: PetView) => sagiPrefs.setPet({ id: p.id, kind: p.kind, name: p.displayName });
   const install = (featuredId: string) =>
     run(featuredId, async () => {
       wear((await api.pets.installFeatured(featuredId)).pet);

client/src/components/Sagi/useSagiBrain.ts

@@ -2,8 +2,12 @@
  * @file useSagiBrain.ts
  * @description React hook that wires the pure Sagi brain to the live event bus
  *   and to real timers. It is the only unit that subscribes to `eventBus`. It
- *   exposes the derived mood, a status summary, the current speech bubble, and
- *   imperative controls (mute, clear alerts, set thinking) for the UI shell.
+ *   exposes the derived mood, a status summary, the sessions that need the user,
+ *   the current speech bubble (naming the session it is about, and coalescing a
+ *   burst of the same event into one count), the pet's one-shot animation
+ *   "moment", and imperative controls (mute, clear alerts, pat, set thinking)
+ *   for the UI shell. It also greets once per browser session and makes an
+ *   idle pet fidget now and then.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 /* =============================================================================
@@ -62,127 +66,303 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { eventBus } from "../../lib/eventBus";
 import { api } from "../../lib/api";
+import i18n from "../../i18n";
 import type { WSMessage } from "../../lib/types";
 import {
   initialSagiState,
   reduceSagi,
   deriveMood,
   statusOf,
+  attentionOf,
   clearErrors,
   seedSessions,
+  subjectLabel,
+  MOMENT_OF_PULSE,
+  type AttentionItem,
   type Mood,
+  type PetMoment,
+  type SagiPulse,
   type SagiState,
   type SagiStatus,
+  type SagiSubject,
 } from "./brain";
-import { pickQuip } from "./quips";
+import { greetingKey, pickLine, pickQuip } from "./quips";
+import { statusSummary } from "./intents";
 import { sagiPrefs } from "./prefs";
 
+/** `next` differs from `prev` only by a lastActivityAt less than a second
+ *  newer — nothing the mascot shows, at the moods' 1 s resolution. */
+function onlyActivityMoved(prev: SagiState, next: SagiState): boolean {
+  if (next === prev) return true;
+  if (next.lastActivityAt - prev.lastActivityAt >= 1000) return false;
+  for (const k of Object.keys(next) as (keyof SagiState)[]) {
+    if (k !== "lastActivityAt" && next[k] !== prev[k]) return false;
+  }
+  return true;
+}
+
 const BUBBLE_MS = 4500;
+// A bubble that names a session stays long enough to click it.
+const SUBJECT_BUBBLE_MS = 7000;
 // Minimum gap between non-error bubbles, so a burst of activity doesn't spam.
 const BUBBLE_THROTTLE_MS = 3000;
+// The same pulse again within this window joins the bubble on show as a count.
+const COALESCE_MS = 8000;
+// How long a moment (wave, hop, flinch…) plays over the mood.
+const MOMENT_MS = 2400;
+// An idle pet fidgets (waves or looks around) once in a while.
+const FIDGET_MIN_MS = 45_000;
+const FIDGET_SPAN_MS = 60_000;
+// Greet once per browser session, shortly after the snapshot lands.
+const GREETED_KEY = "agenthub.pet.greeted";
+const GREET_DELAY_MS = 1200;
+
+/** What the speech bubble shows. */
+export interface SagiBubble {
+  text: string;
+  /** Which session(s) it is about, shown under the text. */
+  detail?: string;
+  /** The one session it is about, which a click opens. */
+  subject?: SagiSubject;
+  /** Errors and waits are drawn with an accent. */
+  tone?: "error" | "waiting";
+}
 
 export interface SagiBrain {
   mood: Mood;
   status: SagiStatus;
-  bubble: string | null;
+  /** Errored, then waiting sessions, named. */
+  attention: AttentionItem[];
+  bubble: SagiBubble | null;
   dismissBubble: () => void;
   /** Imperative bubble setter for one-off messages from the shell (e.g. spawn
    *  errors). Bypasses the throttle because the caller decided this message
    *  must be seen right now. Auto-clears after the standard bubble TTL. */
   setBubble: (text: string) => void;
+  /** The one-shot animation playing now, if any; `key` changes per moment so a
+   *  repeat of the same one restarts it. */
+  moment: { kind: PetMoment; key: number } | null;
+  /** Play a moment by hand (an answer, a pat). */
+  playMoment: (kind: PetMoment) => void;
+  /** Pat the pet: a hop, hearts and a happy line right on the pet — shown
+   *  even while the panel or chat is open, and while muted (it was asked). */
+  pat: () => void;
+  /** The pet's answer to a pat, drawn on the pet itself; `key` restarts it. */
+  reaction: { text: string; key: number } | null;
   muted: boolean;
   toggleMute: () => void;
   clearAlerts: () => void;
   setThinking: (v: boolean) => void;
 }
 
+type Burst = { pulse: NonNullable<SagiPulse>; count: number; subjects: SagiSubject[]; at: number };
+
+function burstBubble(b: Burst): SagiBubble {
+  const tone = b.pulse === "error" ? "error" : b.pulse === "waiting" ? "waiting" : undefined;
+  const one = b.subjects.length === 1 ? b.subjects[0] : undefined;
+  const labels = b.subjects.map(subjectLabel);
+  const detail =
+    labels.length > 2
+      ? i18n.t("settings:sagi.bubbleMore", {
+          list: labels.slice(0, 2).join(", "),
+          count: labels.length - 2,
+        })
+      : labels.join(", ") || undefined;
+  const text =
+    b.count > 1 ? i18n.t(`settings:sagi.notify.${b.pulse}`, { count: b.count }) : pickQuip(b.pulse);
+  return { text, detail, subject: one, tone };
+}
+
 export function useSagiBrain(): SagiBrain {
   const now0 = Date.now();
   // Start optimistically connected (idle, open eyes) so the cursor-tracking
   // eyes are live from the first frame instead of after the WebSocket finishes
   // its initial handshake. onConnection below corrects this if it's truly down.
-  const [state, setState] = useState<SagiState>(() => ({
+  const [state, setStateRaw] = useState<SagiState>(() => ({
     ...initialSagiState(now0),
     connected: true,
+    dismissed: sagiPrefs.getDismissed(),
   }));
+  // The reducer runs OUTSIDE React's updater (which StrictMode calls twice),
+  // so a pulse notifies exactly once; this ref is the state it folds into.
+  const stateRef = useRef(state);
+  const update = useCallback((fn: (prev: SagiState) => SagiState) => {
+    const next = fn(stateRef.current);
+    if (next === stateRef.current) return;
+    stateRef.current = next;
+    setStateRaw(next);
+  }, []);
+
   const [tick, setTick] = useState(now0);
-  const [bubble, setBubbleState] = useState<string | null>(null);
+  const [bubble, setBubbleState] = useState<SagiBubble | null>(null);
+  const [moment, setMoment] = useState<SagiBrain["moment"]>(null);
+  const [reaction, setReaction] = useState<SagiBrain["reaction"]>(null);
+  const reactionTimer = useRef<ReturnType<typeof setTimeout>>();
   const [muted, setMuted] = useState<boolean>(() => sagiPrefs.getMuted());
 
   const bubbleTimer = useRef<ReturnType<typeof setTimeout>>();
+  const momentTimer = useRef<ReturnType<typeof setTimeout>>();
   const lastBubbleAt = useRef(0);
+  const burst = useRef<Burst | null>(null);
+  const momentKey = useRef(0);
   const mutedRef = useRef(muted);
   mutedRef.current = muted;
 
+  // Keep cleared alerts cleared across reloads.
+  useEffect(() => sagiPrefs.setDismissed(state.dismissed), [state.dismissed]);
+
   // Keep mute in sync with the Settings page / other tabs.
   useEffect(() => sagiPrefs.subscribe(() => setMuted(sagiPrefs.getMuted())), []);
 
-  const showBubble = useCallback((text: string, force: boolean) => {
-    if (!text) return;
-    if (mutedRef.current) return;
-    const t = Date.now();
-    if (!force && t - lastBubbleAt.current < BUBBLE_THROTTLE_MS) return;
-    lastBubbleAt.current = t;
+  const putBubble = useCallback((b: SagiBubble, ms = BUBBLE_MS) => {
     clearTimeout(bubbleTimer.current);
-    setBubbleState(text);
-    bubbleTimer.current = setTimeout(() => setBubbleState(null), BUBBLE_MS);
+    setBubbleState(b);
+    bubbleTimer.current = setTimeout(() => {
+      setBubbleState(null);
+      burst.current = null;
+    }, ms);
   }, []);
 
+  const playMoment = useCallback((kind: PetMoment) => {
+    clearTimeout(momentTimer.current);
+    setMoment({ kind, key: ++momentKey.current });
+    momentTimer.current = setTimeout(() => setMoment(null), MOMENT_MS);
+  }, []);
+
+  const notify = useCallback(
+    (pulse: NonNullable<SagiPulse>, subject?: SagiSubject) => {
+      playMoment(MOMENT_OF_PULSE[pulse]);
+      if (mutedRef.current) return;
+      const t = Date.now();
+      const b = burst.current;
+      // The same kind of news again, while its bubble is still up: count it in.
+      if (b && b.pulse === pulse && t - b.at < COALESCE_MS) {
+        b.count++;
+        b.at = t;
+        if (subject && !b.subjects.some((s) => s.id === subject.id)) b.subjects.push(subject);
+        putBubble(burstBubble(b), SUBJECT_BUBBLE_MS);
+        return;
+      }
+      const force = pulse === "error" || pulse === "waiting";
+      if (!force && t - lastBubbleAt.current < BUBBLE_THROTTLE_MS) return;
+      lastBubbleAt.current = t;
+      const next: Burst = { pulse, count: 1, subjects: subject ? [subject] : [], at: t };
+      burst.current = next;
+      putBubble(burstBubble(next), subject ? SUBJECT_BUBBLE_MS : BUBBLE_MS);
+    },
+    [playMoment, putBubble]
+  );
+
   // Seed from the REST snapshot on mount so counts are accurate immediately -
   // the brain otherwise only learns about sessions from WS deltas that arrive
   // after it mounts, showing "0 live" on a fresh load even when sessions exist.
   // Pull a generous page of non-finished sessions; live WS deltas refine it.
+  // Then say hello, once per browser session.
   useEffect(() => {
     let cancelled = false;
+    let greetTimer: ReturnType<typeof setTimeout> | undefined;
+    const greet = () => {
+      try {
+        if (sessionStorage.getItem(GREETED_KEY)) return;
+        sessionStorage.setItem(GREETED_KEY, "1");
+      } catch {
+        return; // No storage: rather silent than a hello on every page.
+      }
+      greetTimer = setTimeout(() => {
+        if (cancelled || mutedRef.current) return;
+        const hello = pickLine(`greet.${greetingKey(new Date().getHours())}`);
+        if (!hello) return;
+        lastBubbleAt.current = Date.now();
+        putBubble({ text: hello, detail: statusSummary(statusOf(stateRef.current)) });
+        playMoment("wave");
+      }, GREET_DELAY_MS);
+    };
     api.sessions
       .list({ status: "active", limit: 100 })
       .then((res) => {
         if (cancelled) return;
-        setState((prev) => seedSessions(prev, res.sessions, Date.now()));
+        update((prev) => seedSessions(prev, res.sessions, Date.now()));
       })
-      .catch(() => undefined);
+      .catch(() => undefined)
+      .finally(greet);
     return () => {
       cancelled = true;
+      clearTimeout(greetTimer);
     };
-  }, []);
+  }, [update, putBubble, playMoment]);
 
   // Subscribe to the live stream and connection status.
   useEffect(() => {
     const unsubMsg = eventBus.subscribe((msg: WSMessage) => {
-      const t = Date.now();
-      setState((prev) => {
-        const { state: next, pulse } = reduceSagi(prev, msg, t);
-        if (pulse) showBubble(pickQuip(pulse), pulse === "error");
-        return next;
-      });
+      const prev = stateRef.current;
+      const { state: next, pulse, subject } = reduceSagi(prev, msg, Date.now());
+      // Most frames only move lastActivityAt, which the moods read at a 1 s
+      // resolution: keep the old state then, so a hook burst (several frames a
+      // second) does not re-render the mascot on every frame.
+      if (!onlyActivityMoved(prev, next)) update(() => next);
+      if (pulse) notify(pulse, subject);
     });
     const unsubConn = eventBus.onConnection((connected) => {
-      setState((prev) => ({ ...prev, connected }));
+      update((prev) => (prev.connected === connected ? prev : { ...prev, connected }));
     });
     return () => {
       unsubMsg();
       unsubConn();
     };
-  }, [showBubble]);
+  }, [update, notify]);
 
   // Advance the clock so timed moods (stuck/sleeping, and exit from
   // happy/worried) re-evaluate without needing a new event.
   useEffect(() => {
     // Hidden tab: no re-render; the first visible tick catches the mood up.
+    // Only a tick that changes the mood re-renders: an idle mascot is not
+    // drawn again every second for nothing.
     const id = setInterval(() => {
-      if (document.visibilityState === "visible") setTick(Date.now());
+      if (document.visibilityState !== "visible") return;
+      const now = Date.now();
+      if (deriveMood(stateRef.current, now) !== moodRef.current) setTick(now);
     }, 1000);
     return () => clearInterval(id);
   }, []);
 
-  useEffect(() => () => clearTimeout(bubbleTimer.current), []);
+  useEffect(
+    () => () => {
+      clearTimeout(bubbleTimer.current);
+      clearTimeout(momentTimer.current);
+      clearTimeout(reactionTimer.current);
+    },
+    []
+  );
 
-  const mood = useMemo(() => deriveMood(state, tick), [state, tick]);
+  // Judged at render time: `tick` only moves when the mood would change, so
+  // it may be old when a frame re-renders.
+  const mood = useMemo(() => deriveMood(state, Math.max(tick, Date.now())), [state, tick]);
   const status = useMemo(() => statusOf(state), [state]);
+  const attention = useMemo(() => attentionOf(state), [state]);
+
+  // An idle pet is not a statue: every minute or so it waves or looks around.
+  const moodRef = useRef(mood);
+  moodRef.current = mood;
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout>;
+    const schedule = () => {
+      timer = setTimeout(
+        () => {
+          if (moodRef.current === "idle" && document.visibilityState === "visible")
+            playMoment(Math.random() < 0.5 ? "wave" : "review");
+          schedule();
+        },
+        FIDGET_MIN_MS + Math.random() * FIDGET_SPAN_MS
+      );
+    };
+    schedule();
+    return () => clearTimeout(timer);
+  }, [playMoment]);
 
   const dismissBubble = useCallback(() => {
     clearTimeout(bubbleTimer.current);
     setBubbleState(null);
+    burst.current = null;
   }, []);
 
   const toggleMute = useCallback(() => {
@@ -192,29 +372,47 @@ export function useSagiBrain(): SagiBrain {
     if (next) dismissBubble();
   }, [dismissBubble]);
 
-  const clearAlerts = useCallback(() => setState((prev) => clearErrors(prev)), []);
+  const clearAlerts = useCallback(() => {
+    update((prev) => clearErrors(prev));
+    if (burst.current?.pulse === "error") dismissBubble();
+  }, [update, dismissBubble]);
 
   const setThinking = useCallback(
-    (v: boolean) => setState((prev) => (prev.thinking === v ? prev : { ...prev, thinking: v })),
-    []
+    (v: boolean) => update((prev) => (prev.thinking === v ? prev : { ...prev, thinking: v })),
+    [update]
   );
 
   // One-shot bubble: clears itself after BUBBLE_MS. Used by the shell for
   // imperative messages (e.g. spawn errors) that must appear now and fade,
   // bypassing the throttled mood-driven showBubble path.
-  const setBubble = useCallback((text: string) => {
-    if (!text) return;
-    clearTimeout(bubbleTimer.current);
-    setBubbleState(text);
-    bubbleTimer.current = setTimeout(() => setBubbleState(null), BUBBLE_MS);
-  }, []);
+  const setBubble = useCallback(
+    (text: string) => {
+      if (!text) return;
+      burst.current = null;
+      putBubble({ text });
+    },
+    [putBubble]
+  );
+
+  const pat = useCallback(() => {
+    playMoment("jump");
+    update((prev) => ({ ...prev, happyUntil: Date.now() + MOMENT_MS }));
+    clearTimeout(reactionTimer.current);
+    setReaction({ text: pickLine("pat"), key: ++momentKey.current });
+    reactionTimer.current = setTimeout(() => setReaction(null), MOMENT_MS);
+  }, [playMoment, update]);
 
   return {
     mood,
     status,
+    attention,
     bubble,
     dismissBubble,
     setBubble,
+    moment,
+    playMoment,
+    pat,
+    reaction,
     muted,
     toggleMute,
     clearAlerts,

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`. */
@@ -144,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

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 — in server mode with the signed-in account above them (its avatar, name and role, linking to Settings → Account, and Log out). 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,12 +49,15 @@
 
 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 {
   LayoutDashboard,
   FolderOpen,
+  HardDrive,
+  Gem,
   BarChart3,
   Settings,
   Wifi,
@@ -70,11 +73,13 @@ import {
   ChevronDown,
   FolderTree,
   LogOut,
-  UsersRound,
+  ShieldCheck,
 } 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 { UserAvatar } from "./users/UserAvatar";
 import { eventBus } from "../lib/eventBus";
 import { WorkspaceTree } from "./WorkspaceTree";
 import type { UpdateStatusPayload, WSMessage } from "../lib/types";
@@ -86,15 +91,12 @@ function isUpdatePayload(x: unknown): x is UpdateStatusPayload {
 const NAV_KEYS = [
   { to: "/", icon: LayoutDashboard, key: "nav:dashboard" },
   { to: "/sessions", icon: FolderOpen, key: "nav:sessions" },
+  // The file manager (FilesPage): browse, upload and download workspace files.
+  { to: "/files", icon: HardDrive, key: "nav:files" },
+  // What agents produced, and (server mode) the Hub others shared (Artifacts.tsx).
+  { to: "/artifacts", icon: Gem, key: "nav:artifacts" },
 ] 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;
@@ -192,8 +194,15 @@ export function Sidebar({
 }: 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 perms = usePermissions();
+  const canUpdate = perms.isAdmin;
   const asideRef = useRef<HTMLElement>(null);
   const drawerOpen = Boolean(drawer?.open);
   useDialog(drawerOpen, asideRef, drawer?.onClose);
@@ -468,12 +477,13 @@ export function Sidebar({
       <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,
-            // Server mode: the Users page, for an admin or analyst.
+            // The file manager serves a shared server; locally it is the desktop's.
+            ...NAV_KEYS.filter((n) => !(perms.local && n.to === "/files")),
+            // Server mode: Administration (users, server), for an admin or analyst.
             ...(auth.state.mode === "server" &&
             auth.state.user &&
             auth.state.user.role !== "developer"
-              ? [{ to: "/users", icon: UsersRound, key: "nav:users" }]
+              ? [{ to: "/admin", icon: ShieldCheck, key: "nav:admin" }]
               : []),
           ].map(({ to, icon: Icon, key }) => {
             const label = t(key);
@@ -496,6 +506,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"
@@ -530,6 +541,59 @@ export function Sidebar({
         )}
       </div>
 
+      {/* Server mode: who is signed in — avatar, name and role, opening
+          Settings → Account — and Log out. On the rail they stack. */}
+      {auth.state.mode === "server" &&
+        auth.state.user &&
+        (() => {
+          const user = auth.state.user;
+          const name = user.displayName || user.username;
+          const role = t(`users:roles.${user.role}`);
+          const signedIn = t("common:auth.signedInAs", { name, role });
+          return (
+            <div
+              data-testid="sidebar-account"
+              className={`flex flex-shrink-0 gap-1 border-t border-border px-2 py-2 ${
+                collapsed ? "flex-col items-center" : "items-center"
+              }`}
+            >
+              <NavLink
+                to={settingsHref("account", location)}
+                title={signedIn}
+                aria-label={signedIn}
+                className={`flex min-w-0 items-center gap-2 rounded-md transition-colors hover:bg-surface-3 ${
+                  collapsed ? "justify-center p-1" : "flex-1 px-1.5 py-1"
+                }`}
+              >
+                <UserAvatar
+                  name={name}
+                  avatarAt={user.avatarAt}
+                  className={collapsed ? "h-7 w-7 text-[11px]" : "h-8 w-8 text-xs"}
+                />
+                {!collapsed && (
+                  <span className="min-w-0 leading-tight">
+                    <span className="block truncate text-sm font-medium text-fg-primary">
+                      {name}
+                    </span>
+                    <span className="block truncate text-[11px] text-fg-muted">{role}</span>
+                  </span>
+                )}
+              </NavLink>
+              <button
+                type="button"
+                onClick={() => void auth.logout()}
+                title={`${signedIn} — ${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 ? "w-full py-2" : "h-8 w-8 flex-shrink-0"
+                }`}
+              >
+                <LogOut className="h-4 w-4" />
+              </button>
+            </div>
+          );
+        })()}
+
       {/* Settings and the collapse toggle stick to the foot, out of the
           scrolling nav. On the rail they stack. */}
       <div
@@ -538,29 +602,13 @@ 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}

client/src/components/SplashScreen.tsx

@@ -1,7 +1,7 @@
 /**
  * @file SplashScreen.tsx
  * @description Branding splash shown once per browser session on app load. A
- * dark-tech "constellation" overlay built around the node-graph brand mark:
+ * dark-tech "constellation" overlay built around the SmartGift brand mark:
  * a time-aware greeting, a bold (localized) tagline, and two subtexts reveal
  * in a staggered cascade. The tagline and the subtext pair are picked at
  * random (per mount) from localized pools in `splash.json`, so the copy is
@@ -143,7 +143,7 @@ export function SplashScreen() {
       <div className="splash-grain" aria-hidden="true" />
 
       <div className="splash-content">
-        {/* Brand mark - the node-graph hexagon, enlarged and animated */}
+        {/* Brand mark - the SmartGift logo */}
         <div className="splash-mark" aria-hidden="true">
           <span className="splash-mark-glow" />
           <BrandMark />
@@ -167,74 +167,10 @@ export function SplashScreen() {
   );
 }
 
-/** The hexagon node-graph brand mark (mirrors public/favicon.svg), scaled up
- *  with animated connector lines and pulsing outer nodes. */
+/** The SmartGift mark — the same file as the favicon, local so the splash
+ *  needs no network. */
 function BrandMark() {
-  return (
-    <svg viewBox="0 0 32 32" width="96" height="96" className="splash-svg">
-      <defs>
-        <linearGradient id="splashBg" x1="0%" y1="0%" x2="100%" y2="100%">
-          <stop offset="0%" stopColor="#6366f1" />
-          <stop offset="100%" stopColor="#818cf8" />
-        </linearGradient>
-        <linearGradient id="splashGlow" x1="0%" y1="0%" x2="100%" y2="100%">
-          <stop offset="0%" stopColor="#a5b4fc" stopOpacity="0.95" />
-          <stop offset="100%" stopColor="#c7d2fe" stopOpacity="0.6" />
-        </linearGradient>
-      </defs>
-      <polygon
-        className="splash-hex"
-        points="16,2 28,9 28,23 16,30 4,23 4,9"
-        fill="url(#splashBg)"
-      />
-      <circle cx="16" cy="16" r="3" fill="white" opacity="0.95" />
-      <line
-        className="splash-line"
-        x1="16"
-        y1="13"
-        x2="16"
-        y2="7"
-        stroke="white"
-        strokeWidth="1.5"
-        strokeLinecap="round"
-      />
-      <line
-        className="splash-line splash-line-2"
-        x1="18.6"
-        y1="17.5"
-        x2="24"
-        y2="20.5"
-        stroke="white"
-        strokeWidth="1.5"
-        strokeLinecap="round"
-      />
-      <line
-        className="splash-line splash-line-3"
-        x1="13.4"
-        y1="17.5"
-        x2="8"
-        y2="20.5"
-        stroke="white"
-        strokeWidth="1.5"
-        strokeLinecap="round"
-      />
-      <circle className="splash-node" cx="16" cy="6" r="1.8" fill="url(#splashGlow)" />
-      <circle
-        className="splash-node splash-node-2"
-        cx="24.5"
-        cy="21"
-        r="1.8"
-        fill="url(#splashGlow)"
-      />
-      <circle
-        className="splash-node splash-node-3"
-        cx="7.5"
-        cy="21"
-        r="1.8"
-        fill="url(#splashGlow)"
-      />
-    </svg>
-  );
+  return <img src="/favicon.svg" alt="" width={96} height={96} className="splash-svg" />;
 }
 
 /** Faint background constellation: a handful of nodes joined by thin lines that
@@ -351,13 +287,6 @@ const SPLASH_CSS = `
   animation: splashGlowPulse 2.6s ease-in-out infinite;
 }
 .splash-svg { position: relative; display: block; filter: drop-shadow(0 8px 28px rgba(99, 102, 241, 0.45)); }
-.splash-hex { transform-origin: center; animation: splashHexBreathe 3.4s ease-in-out infinite; }
-.splash-line { stroke-dasharray: 8; stroke-dashoffset: 8; opacity: 0.75; animation: splashDraw 0.7s ease 0.5s forwards; }
-.splash-line-2 { animation-delay: 0.62s; }
-.splash-line-3 { animation-delay: 0.74s; }
-.splash-node { opacity: 0; animation: splashNodePop 0.5s ease 0.85s forwards, splashNodePulse 2.4s ease-in-out 1.4s infinite; }
-.splash-node-2 { animation-delay: 0.98s, 1.6s; }
-.splash-node-3 { animation-delay: 1.1s, 1.8s; }
 
 .splash-greeting {
   display: flex;
@@ -435,11 +364,7 @@ const SPLASH_CSS = `
 @keyframes splashDrift { from { transform: translate3d(0, 0, 0); } to { transform: translate3d(-24px, -16px, 0) scale(1.05); } }
 @keyframes splashTwinkle { 0%, 100% { opacity: 0.25; } 50% { opacity: 0.7; } }
 @keyframes splashMark { from { opacity: 0; transform: translateY(14px) scale(0.82); } to { opacity: 1; transform: translateY(0) scale(1); } }
-@keyframes splashHexBreathe { 0%, 100% { transform: scale(1); } 50% { transform: scale(1.04); } }
 @keyframes splashGlowPulse { 0%, 100% { opacity: 0.55; transform: scale(0.96); } 50% { opacity: 1; transform: scale(1.06); } }
-@keyframes splashDraw { to { stroke-dashoffset: 0; } }
-@keyframes splashNodePop { from { opacity: 0; transform: scale(0); } to { opacity: 1; transform: scale(1); } }
-@keyframes splashNodePulse { 0%, 100% { opacity: 0.7; } 50% { opacity: 1; } }
 @keyframes splashRise { from { opacity: 0; transform: translateY(18px); } to { opacity: 1; transform: translateY(0); } }
 
 @media (prefers-reduced-motion: reduce) {
@@ -449,9 +374,6 @@ const SPLASH_CSS = `
   .splash-star,
   .splash-mark,
   .splash-mark-glow,
-  .splash-hex,
-  .splash-line,
-  .splash-node,
   .splash-dot,
   .splash-greeting,
   .splash-tagline,
@@ -460,7 +382,6 @@ const SPLASH_CSS = `
     animation-duration: 0.01ms !important;
     animation-iteration-count: 1 !important;
     opacity: 1 !important;
-    stroke-dashoffset: 0 !important;
     transform: none !important;
   }
 }

client/src/components/StatusBar.tsx

@@ -9,8 +9,12 @@
  * Workspace page, the open workspace's total (`?lane=` on the same call: the
  * sessions it owns) and the shown session's (`GET /api/pricing/cost/:id` for
  * the URL's `session`, or the focused pane's session from the page's run poll,
- * `LIVE_RUNS_EVENT`), all re-read every 30 s while the tab is visible and
- * whenever the URL names another workspace or session. Each figure carries its
+ * `LIVE_RUNS_EVENT`), all re-read at once whenever the URL names another
+ * workspace or session, then at most every 30 s while events or session
+ * updates arrive (spend only moves with work) and every 2 min otherwise, while
+ * the tab is visible. The session counts re-read only when a session is
+ * created or its status / waiting / archived state changes (every 60 s
+ * otherwise). Each figure carries its
  * token total, and hovering it lists tokens and cost per model. At the right
  * end, the plan quota spent per native tool (`GET /api/pricing/quota`, every
  * 5 min while visible; a click forces a re-read): one "N% used" chip per tool —
@@ -31,9 +35,15 @@ import { fmt, fmtCostFull, formatModelName, timeAgo } from "../lib/format";
 import { AiToolIcon } from "./AiToolIcon";
 import { useLiveRefresh } from "../hooks/useLiveRefresh";
 import { useSpin } from "../hooks/useSpin";
+import { sessionChangeMatcher } from "../lib/sessionChange";
 import { LIVE_RUNS_EVENT, selectedFrom } from "./WorkspaceTree";
 
+/** Spend moves only with work: at most this often while events arrive… */
 const COST_POLL_MS = 30_000;
+/** …and this often regardless (date rollover, budget period, a missed frame). */
+const COST_FALLBACK_MS = 120_000;
+/** The counts' safety poll; session frames that change a count drive the rest. */
+const COUNTS_FALLBACK_MS = 60_000;
 const QUOTA_POLL_MS = 5 * 60_000;
 const QUOTA_TOOL_LABEL: Record<ToolQuota["id"], string> = {
   claude: "Claude",
@@ -384,51 +394,57 @@ export function StatusBar({
       .catch(() => undefined);
   }, []);
   useEffect(loadCounts, [loadCounts]);
-  useLiveRefresh(loadCounts, {
-    intervalMs: 15_000,
-    match: (msg) => msg.type === "session_updated" || msg.type === "session_created",
-  });
+  // Only a frame that moves a session between the counted states (a new
+  // session, a status / waiting / archived change) re-reads: a session row is
+  // re-broadcast on almost every hook.
+  const [countsChanged] = useState(() => sessionChangeMatcher());
+  useLiveRefresh(loadCounts, { intervalMs: COUNTS_FALLBACK_MS, match: countsChanged });
 
+  // Bumped on every lane/session switch: an answer for the previous one is dropped.
+  const costGen = useRef(0);
+  const loadCosts = useCallback(() => {
+    const gen = costGen.current;
+    const live = () => gen === costGen.current;
+    api.pricing
+      .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 })
+        .then((r) => live() && setLaneCost(r))
+        .catch(() => undefined);
+    }
+    if (sessionId) {
+      api.pricing
+        .sessionCost(sessionId)
+        .then((r) => live() && setSessionCost(r))
+        .catch(() => undefined);
+    }
+  }, [lane, sessionId]);
   useEffect(() => {
-    let live = true;
+    costGen.current++;
     // Another workspace or session: never show the previous one's figure.
     setLaneCost(null);
     setSessionCost(null);
-    const tick = () => {
-      if (document.visibilityState !== "visible") return;
-      api.pricing
-        .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 })
-          .then((r) => live && setLaneCost(r))
-          .catch(() => undefined);
-      }
-      if (sessionId) {
-        api.pricing
-          .sessionCost(sessionId)
-          .then((r) => live && setSessionCost(r))
-          .catch(() => undefined);
-      }
-    };
-    tick();
-    const id = setInterval(tick, COST_POLL_MS);
-    document.addEventListener("visibilitychange", tick);
+    if (document.visibilityState === "visible") loadCosts();
     return () => {
-      live = false;
-      clearInterval(id);
-      document.removeEventListener("visibilitychange", tick);
+      costGen.current++;
     };
-  }, [lane, sessionId]);
+  }, [loadCosts]);
+  useLiveRefresh(loadCosts, {
+    intervalMs: COST_FALLBACK_MS,
+    throttleMs: COST_POLL_MS,
+    match: (msg) =>
+      msg.type === "new_event" || msg.type === "session_updated" || msg.type === "session_created",
+  });
 
   return (
     <footer

client/src/components/Switch.tsx

@@ -33,13 +33,16 @@ export function Switch({
       // On: the solid accent (white knob clears 3:1 in every theme). Off: a
       // border-light track with an inset fg-muted/80 ring (≥3:1 in every theme), so the control's edge
       // is visible on any surface (surface-4 alone was ~1:1 on a light card).
-      className={`relative inline-flex h-5 w-9 shrink-0 items-center rounded-full transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-surface-0 disabled:cursor-not-allowed disabled:opacity-50 ${
-        checked ? "bg-accent-solid" : "bg-border-light ring-1 ring-inset ring-fg-muted/80"
+      // Hover darkens the track (enabled only), so it reads as clickable.
+      className={`relative inline-flex h-5 w-9 shrink-0 items-center rounded-full transition-colors duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-surface-0 disabled:cursor-not-allowed disabled:opacity-40 ${
+        checked
+          ? "bg-accent-solid enabled:hover:bg-accent-solid-hover"
+          : "bg-border-light ring-1 ring-inset ring-fg-muted/80 enabled:hover:ring-fg-secondary"
       }`}
     >
       <span
         aria-hidden
-        className={`inline-block h-4 w-4 rounded-full bg-white shadow transition-transform ${
+        className={`inline-block h-4 w-4 rounded-full bg-white shadow-sm ring-1 ring-black/10 transition-transform duration-200 ease-out ${
           checked ? "translate-x-[18px]" : "translate-x-0.5"
         }`}
       />

client/src/components/UpdateNotifier.tsx

@@ -16,9 +16,13 @@
  * — and the poll waits for the old server to actually go DOWN first, because it
  * keeps answering while the chain installs. New skills/slash commands still
  * need `/reload-plugins` in an already-open Claude Code session; nothing a
- * background process can do for it. Escape, the backdrop and "Not now" close it
- * for this page load only (never while applying); "Skip this version" is the
- * one persistent, per-version dismiss.
+ * background process can do for it. Escape, the backdrop and × close it for
+ * this page load only (never while applying); "Skip this version" is the one
+ * persistent, per-version dismiss. After a failed update, "Auto fix" hands the
+ * error to an AI agent: it opens (or adopts) a workspace on the install folder
+ * and starts a Claude Code session there with the error as its prompt — the
+ * agent fixes whatever blocked the update (a dirty lockfile, a failed build…)
+ * and runs the update command; the dashboard itself still decides nothing.
  *
  * ## State sources
  * - Initial fetch via `api.updates.status()` on mount.
@@ -81,7 +85,18 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { Download, X, Copy, Check, RefreshCw, Zap, ExternalLink } from "lucide-react";
+import { useNavigate } from "react-router-dom";
+import {
+  Download,
+  X,
+  Copy,
+  Check,
+  RefreshCw,
+  Zap,
+  ExternalLink,
+  SkipForward,
+  Wrench,
+} from "lucide-react";
 import { api } from "../lib/api";
 import { eventBus } from "../lib/eventBus";
 import { copyText } from "../lib/clipboard";
@@ -89,6 +104,7 @@ import { toast } from "../lib/toast";
 import { useDialog } from "../hooks/useDialog";
 import type { UpdateStatusPayload, WSMessage } from "../lib/types";
 import { usePermissions } from "./AuthGate";
+import { startInFreeTab } from "./lanes/startSession";
 
 /** `localStorage` key storing the dismissed release tag (or upstream SHA). */
 const DISMISS_KEY = "agent-monitor-update-dismissed-sha";
@@ -107,6 +123,32 @@ function isAutoApplicable(situation: UpdateStatusPayload["situation"]): boolean
   );
 }
 
+/** The prompt the Auto fix session starts with: what failed, where, and the
+ *  limits that keep the agent from taking down the dashboard it runs under. */
+function autoFixPrompt(status: UpdateStatusPayload, error: string): string {
+  const target = status.latest_release || status.remote_ref || "the newest version";
+  const plugin = status.situation === "plugin_managed";
+  return [
+    `The AgentHub dashboard's self-update to ${target} failed${status.local_version ? ` (running ${status.local_version})` : ""}.`,
+    plugin
+      ? "AgentHub is installed as a Claude Code plugin (the `agenthub` plugin from the `agenthub` marketplace)."
+      : `The install is the git checkout at ${status.repo_root}.`,
+    "",
+    "Error:",
+    "```",
+    error,
+    "```",
+    ...(status.manual_command ? ["", "Update command:", "```", status.manual_command, "```"] : []),
+    "",
+    "Find the cause, fix it, then finish the update" +
+      (plugin
+        ? " (`claude plugin marketplace update agenthub` then `claude plugin update agenthub@agenthub`)."
+        : " by running the update command."),
+    "Rules: never lose the user's work — before discarding any local change, save it (e.g. `git diff > ~/agenthub-update-backup.patch`) and say where; do not stop or restart the AgentHub server, and never kill tmux sessions or the tmux server (this session runs inside one).",
+    "When done, tell me what you changed; I will restart the dashboard from its update prompt.",
+  ].join("\n");
+}
+
 /** Narrow unknown WebSocket payloads to {@link UpdateStatusPayload}. */
 function isUpdatePayload(x: unknown): x is UpdateStatusPayload {
   return typeof x === "object" && x !== null && "git_repo" in x && "update_available" in x;
@@ -130,7 +172,7 @@ export function UpdateNotifier() {
   const { t } = useTranslation("updates");
   const [status, setStatus] = useState<UpdateStatusPayload | null>(null);
   const [dismissedSha, setDismissedSha] = useState<string | null>(loadDismissedSha);
-  // Closed for THIS page load only (Escape, backdrop, ×, "Not now") — the
+  // Closed for THIS page load only (Escape, backdrop, ×) — the
   // persistent per-version dismiss is the explicit "Skip this version".
   const [closedKey, setClosedKey] = useState<string | null>(null);
   const panelRef = useRef<HTMLDivElement>(null);
@@ -139,6 +181,8 @@ export function UpdateNotifier() {
   const [checking, setChecking] = useState(false);
   const [applying, setApplying] = useState(false);
   const [restarting, setRestarting] = useState(false);
+  const [fixing, setFixing] = useState(false);
+  const navigate = useNavigate();
 
   const syncFromPayload = useCallback((s: UpdateStatusPayload) => {
     setStatus(s);
@@ -200,7 +244,7 @@ export function UpdateNotifier() {
     dismissedSha !== dismissKey &&
     closedKey !== dismissKey
   );
-  const busy = applying || restarting;
+  const busy = applying || restarting || fixing;
 
   const closeForNow = useCallback(() => {
     if (busy || !dismissKey) return;
@@ -317,6 +361,29 @@ export function UpdateNotifier() {
     }
   };
 
+  // Hand the failure to an AI agent: a workspace on the install folder (the
+  // home for a plugin install — never a lane inside the plugin cache) and a
+  // Claude Code session there with the error as its first prompt.
+  const autoFix = async () => {
+    if (busy || !status || !error) return;
+    setFixing(true);
+    try {
+      const plugin = status.situation === "plugin_managed";
+      const { lane } = await api.lanes.ensure({
+        ...(plugin || !status.repo_root ? {} : { cwd: status.repo_root, exact: true }),
+        title: t("autoFixWorkspace"),
+        tool: "claude",
+      });
+      const runId = await startInFreeTab(lane.id, { prompt: autoFixPrompt(status, error) });
+      if (dismissKey) setClosedKey(dismissKey);
+      navigate(`/workspace?lane=${lane.id}&run=${encodeURIComponent(runId)}`);
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : t("autoFixError"));
+    } finally {
+      setFixing(false);
+    }
+  };
+
   if (!show || !status) return null;
 
   const refLabel = status.remote_ref || "origin";
@@ -463,7 +530,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}
@@ -490,16 +560,9 @@ export function UpdateNotifier() {
             title={t("skipVersionHint")}
             className="btn-ghost disabled:opacity-60 disabled:cursor-not-allowed"
           >
+            <SkipForward className="w-3.5 h-3.5" aria-hidden />
             {t("skipVersion")}
           </button>
-          <button
-            type="button"
-            onClick={closeForNow}
-            disabled={busy}
-            className="btn-ghost disabled:opacity-60 disabled:cursor-not-allowed"
-          >
-            {t("later")}
-          </button>
           {status.manual_command ? (
             <button
               type="button"
@@ -511,11 +574,28 @@ export function UpdateNotifier() {
               {copied ? t("copied") : t("copy")}
             </button>
           ) : null}
+          {/* Only after a failed update: an AI agent takes the error from here. */}
+          {error ? (
+            <button
+              type="button"
+              onClick={autoFix}
+              disabled={busy}
+              title={t("autoFixHint")}
+              className="btn-ghost disabled:opacity-60 disabled:cursor-not-allowed"
+            >
+              {fixing ? (
+                <RefreshCw className="w-3.5 h-3.5 animate-spin" aria-hidden />
+              ) : (
+                <Wrench className="w-3.5 h-3.5" aria-hidden />
+              )}
+              {t("autoFix")}
+            </button>
+          ) : null}
           {isAutoApplicable(status.situation) ? (
             <button
               type="button"
               onClick={applyNow}
-              disabled={applying || restarting}
+              disabled={busy}
               className="btn-primary disabled:opacity-70"
             >
               {applying || restarting ? (

client/src/components/WorkspaceTree.tsx

@@ -5,11 +5,16 @@
  * (`WorkspaceSessionList.tsx`) — no repo grouping, no worktree rows. Picking a
  * 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 (`useWorkLanes`), live panes from `GET /api/run`, re-read whenever a
+ * lane list (`useLanes`), live panes from `GET /api/run`, re-read whenever a
  * 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`).
+ * expanded lives in `projectTreePrefs.ts` (`expanded`). Server mode, admin or
+ * analyst: EVERY workspace, grouped under its owner (their avatar —
+ * `owner_avatar_at`, `UserAvatar` — and `owner_display_name`, else `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>
  */
 
@@ -25,10 +30,11 @@ import {
 } 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 { useWorkLanes } from "../hooks/useLanes";
+import { useLanes } from "../hooks/useLanes";
+import { useAuth, usePermissions } from "./AuthGate";
 import { useAiTools } from "../hooks/useAiTools";
 import { useThrottledValue } from "../hooks/useThrottledValue";
 import {
@@ -43,6 +49,7 @@ 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 { UserAvatar } from "./users/UserAvatar";
 
 // The sidebar is in the entry chunk; its two modals (and the run form the add
 // modal pulls in) load when first opened.
@@ -55,6 +62,9 @@ const DestructiveLaneModal = lazy(() =>
 
 /** 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). */
+/** An owner as the tree shows it: their display name, else their username. */
+const ownerShown = (l: Lane): string => l.owner_display_name || l.owner_name || "";
+
 export function selectedFrom(pathname: string, search: string) {
   if (!pathname.startsWith("/workspace")) return { lane: null, run: null, session: null };
   const p = new URLSearchParams(search);
@@ -70,7 +80,12 @@ export function WorkspaceTree() {
   const navigate = useNavigate();
   const location = useLocation();
   const selected = selectedFrom(location.pathname, location.search);
-  const { lanes, refresh: refreshLanes } = useWorkLanes();
+  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("");
@@ -132,10 +147,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) || ownerShown(a).localeCompare(ownerShown(b))
+    );
+  }, [lanes, order, toolFilter, grouped, meId]);
   const q = query.trim().toLowerCase();
   const nameHit = (l: Lane) =>
     workspaceName(l).toLowerCase().includes(q) || l.cwd.toLowerCase().includes(q);
@@ -312,42 +334,92 @@ 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: ownerShown(lane) || `#${lane.owner_id}` })
+                : ownerShown(lane) || `#${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" />
+                  )}
+                  <UserAvatar
+                    name={ownerShown(lane) || "?"}
+                    userId={lane.owner_id ?? undefined}
+                    avatarAt={lane.owner_avatar_at}
+                    letters={1}
+                    className="h-4 w-4 text-[9px]"
+                    initialsClassName="bg-surface-4 text-fg-secondary"
+                  />
+                  <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 />
@@ -400,6 +472,9 @@ export function WorkspaceTree() {
   );
 }
 
+/** 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__/AuthGate.test.tsx

@@ -5,17 +5,19 @@
  * 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.
+ * 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 } from "@testing-library/react";
+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 },
@@ -25,6 +27,7 @@ vi.mock("../../lib/api", () => ({
   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: {} }) },
   },
 }));
 
@@ -52,6 +55,7 @@ const user = { id: 1, username: "mia", role: "developer" };
 beforeEach(() => {
   me.mockReset();
   login.mockReset();
+  prefs.mockReset().mockResolvedValue({ prefs: {} });
   localStorage.clear();
 });
 
@@ -107,15 +111,15 @@ describe("AuthGate", () => {
     render(<AuthGate>app</AuthGate>);
 
     const name = await screen.findByLabelText(/username/i);
-    const pass = screen.getByLabelText(/password/i);
+    const pass = screen.getByLabelText(/^password$/i);
     await userEvent.type(name, "mia");
     await userEvent.type(pass, "nope");
-    await userEvent.click(screen.getByRole("button"));
+    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"));
+    await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
     expect(await screen.findByText("app")).toBeInTheDocument();
     expect(login).toHaveBeenLastCalledWith("mia", "member-pass-1");
 
@@ -126,6 +130,32 @@ describe("AuthGate", () => {
   });
 });
 
+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();

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

@@ -1,21 +1,21 @@
 /**
  * @file PathPickButton.test.tsx
  * @description Unit tests for the Browse button beside path fields: a chosen
- * path fills the field, a Cancel changes nothing, a folder falls back to the
- * in-app browser on ANY native-picker failure, and a file falls back to a
- * "type the path" hint only when no picker exists for this browser.
+ * path fills the field, a Cancel changes nothing, and a folder or a file falls
+ * back to the in-app browser on ANY native-picker failure (a LAN browser's
+ * EREMOTE included), where a double-click on a file picks it.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, waitFor } from "@testing-library/react";
+import { render, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { api } from "../../lib/api";
 import { toast } from "../../lib/toast";
 import { PathPickButton } from "../PathPickButton";
 
 vi.mock("../../lib/api", () => ({
-  api: { lanes: { pickPath: vi.fn(), browse: vi.fn() } },
+  api: { lanes: { pickPath: vi.fn(), browse: vi.fn(), list: vi.fn(() => new Promise(() => {})) } },
 }));
 vi.mock("../../lib/toast", () => ({
   toast: { info: vi.fn(), error: vi.fn(), success: vi.fn() },
@@ -55,15 +55,24 @@ describe("PathPickButton", () => {
     expect(toast.error).not.toHaveBeenCalled();
   });
 
-  it("hints to type a file path when no picker exists, and reports any other failure", async () => {
-    vi.mocked(api.lanes.pickPath).mockRejectedValueOnce(fail("ENODIALOG"));
-    vi.mocked(api.lanes.pickPath).mockRejectedValueOnce(fail("EDIALOG"));
-    render(<PathPickButton kind="file" onPick={vi.fn()} />);
-    const button = screen.getByRole("button");
-    await userEvent.click(button);
-    await waitFor(() => expect(toast.info).toHaveBeenCalledTimes(1));
-    await userEvent.click(button);
-    await waitFor(() => expect(toast.error).toHaveBeenCalledWith("EDIALOG"));
+  it("opens the in-app browser for a file too, and a double-click on a file picks it", async () => {
+    const onPick = vi.fn();
+    vi.mocked(api.lanes.pickPath).mockRejectedValue(fail("EREMOTE"));
+    vi.mocked(api.lanes.browse).mockResolvedValue({
+      path: "/home/u/.ssh",
+      parent: "/home/u",
+      entries: [
+        { name: "id_ed25519", path: "/home/u/.ssh/id_ed25519", isGitRepo: false, file: true },
+      ],
+    });
+    render(<PathPickButton kind="file" start="~/.ssh" onPick={onPick} />);
+    await userEvent.click(screen.getByRole("button"));
+    const dialog = await screen.findByRole("dialog", { name: "Browse for a file" });
+    expect(api.lanes.browse).toHaveBeenCalledWith("~/.ssh", true, false, false);
+    expect(within(dialog).queryByText("Select this folder")).toBeNull();
+    await userEvent.dblClick(await within(dialog).findByText("id_ed25519"));
+    expect(onPick).toHaveBeenCalledWith("/home/u/.ssh/id_ed25519");
     expect(screen.queryByRole("dialog")).toBeNull();
+    expect(toast.info).not.toHaveBeenCalled();
   });
 });

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__/Sidebar.account.test.tsx

@@ -0,0 +1,73 @@
+/**
+ * @file Sidebar.account.test.tsx
+ * @description The sidebar's account row (server mode): the signed-in user's
+ * avatar — or initials without one — name and role, linking to Settings →
+ * Account, beside Sign out; local mode shows no row.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, within } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+
+const auth = vi.hoisted(() => ({
+  state: { mode: "local" } as Record<string, unknown>,
+  logout: vi.fn(),
+  updateUser: vi.fn(),
+}));
+vi.mock("../AuthGate", () => ({
+  useAuth: () => auth,
+  usePermissions: () => ({
+    isAdmin: auth.state.mode !== "server",
+    local: auth.state.mode !== "server",
+    seesAll: true,
+    canEditLane: () => true,
+  }),
+}));
+
+import { Sidebar } from "../Sidebar";
+
+const renderSidebar = (collapsed = false) =>
+  render(
+    <MemoryRouter>
+      <Sidebar
+        wsConnected
+        collapsed={collapsed}
+        onToggle={() => {}}
+        connectionOpen={false}
+        onConnectionOpenChange={() => {}}
+      />
+    </MemoryRouter>
+  );
+
+describe("Sidebar account row", () => {
+  it("shows the avatar, name and role, linking to Settings → Account", () => {
+    auth.state = {
+      mode: "server",
+      user: { id: 2, username: "mia", role: "developer", displayName: "Mia Tran", avatarAt: "t1" },
+    };
+    renderSidebar();
+    const row = screen.getByTestId("sidebar-account");
+    expect(row.textContent).toContain("Mia Tran");
+    expect(row.textContent).toContain("Developer");
+    expect(within(row).getByTestId("user-avatar-img").getAttribute("src")).toBe(
+      "/api/me/avatar?v=t1"
+    );
+    expect(within(row).getAllByRole("link")[0]?.getAttribute("href")).toBe("/settings/account");
+    expect(within(row).getByRole("button", { name: "Sign out" })).toBeTruthy();
+  });
+
+  it("falls back to initials, and keeps only the avatar on the rail", () => {
+    auth.state = { mode: "server", user: { id: 3, username: "leo", role: "admin" } };
+    renderSidebar(true);
+    const row = screen.getByTestId("sidebar-account");
+    expect(within(row).getByTestId("user-avatar-initials").textContent).toBe("le");
+    expect(row.textContent).not.toContain("Admin");
+  });
+
+  it("has no account row in local mode", () => {
+    auth.state = { mode: "local" };
+    renderSidebar();
+    expect(screen.queryByTestId("sidebar-account")).toBeNull();
+  });
+});

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

@@ -95,6 +95,8 @@ describe("Sidebar", () => {
     expect(hrefs).toContain("/sessions");
     expect(hrefs).toContain("/settings");
     expect(hrefs).not.toContain("/activity");
+    // The file manager serves a shared server; a local dashboard has none.
+    expect(hrefs).not.toContain("/files");
   });
 
   describe("update status line, in the connection details modal", () => {

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

@@ -19,6 +19,18 @@ import type { UpdateStatusPayload } from "../../lib/types";
 const statusMock = vi.fn();
 const checkMock = vi.fn();
 const applyMock = vi.fn();
+const ensureMock = vi.fn();
+const startMock = vi.fn();
+const navigateMock = vi.fn();
+
+vi.mock("react-router-dom", async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useNavigate: () => navigateMock,
+}));
+
+vi.mock("../lanes/startSession", () => ({
+  startInFreeTab: (...args: unknown[]) => startMock(...args),
+}));
 
 vi.mock("../../lib/api", async (importOriginal) => {
   const actual = await importOriginal<Record<string, unknown>>();
@@ -30,6 +42,7 @@ vi.mock("../../lib/api", async (importOriginal) => {
         check: (...args: unknown[]) => checkMock(...args),
         apply: (...args: unknown[]) => applyMock(...args),
       },
+      lanes: { ensure: (...args: unknown[]) => ensureMock(...args) },
     },
   };
 });
@@ -56,6 +69,9 @@ beforeEach(() => {
   statusMock.mockReset().mockResolvedValue(BASE_STATUS);
   checkMock.mockReset().mockResolvedValue(BASE_STATUS);
   applyMock.mockReset();
+  ensureMock.mockReset().mockResolvedValue({ lane: { id: 7 }, created: true });
+  startMock.mockReset().mockResolvedValue("agenthub-lane-7-1");
+  navigateMock.mockReset();
   try {
     localStorage.clear();
   } catch {
@@ -274,7 +290,7 @@ describe("UpdateNotifier — closing vs skipping", () => {
 
   it("Check for updates re-opens a modal closed with Later", async () => {
     render(<UpdateNotifier />);
-    await userEvent.click(await screen.findByText(i18n.t("updates:later")));
+    await userEvent.click(await screen.findByRole("button", { name: i18n.t("updates:later") }));
     await waitFor(() =>
       expect(screen.queryByText(i18n.t("updates:title"))).not.toBeInTheDocument()
     );
@@ -290,3 +306,26 @@ describe("UpdateNotifier — closing vs skipping", () => {
     expect(screen.getByText(i18n.t("updates:title"))).toBeInTheDocument();
   });
 });
+
+describe("UpdateNotifier — Auto fix", () => {
+  it("offers no Not now button, and Auto fix only once an update failed", async () => {
+    applyMock.mockRejectedValue(new Error("Command failed: git merge --ff-only v2.8.0"));
+    render(<UpdateNotifier />);
+    await screen.findByText(i18n.t("updates:updateNow"));
+    expect(screen.queryByText(i18n.t("updates:later"))).not.toBeInTheDocument();
+    expect(screen.queryByText(i18n.t("updates:autoFix"))).not.toBeInTheDocument();
+
+    await userEvent.click(screen.getByText(i18n.t("updates:updateNow")));
+    await userEvent.click(await screen.findByText(i18n.t("updates:autoFix")));
+
+    await waitFor(() => expect(navigateMock).toHaveBeenCalled());
+    expect(ensureMock).toHaveBeenCalledWith(
+      expect.objectContaining({ cwd: "/repo", exact: true, tool: "claude" })
+    );
+    const [laneId, body] = startMock.mock.calls[0] ?? [];
+    expect(laneId).toBe(7);
+    expect(body.prompt).toContain("git merge --ff-only v2.8.0");
+    expect(body.prompt).toContain(BASE_STATUS.manual_command);
+    expect(navigateMock).toHaveBeenCalledWith("/workspace?lane=7&run=agenthub-lane-7-1");
+  });
+});

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

@@ -0,0 +1,170 @@
+/**
+ * @file WorkspaceTree.owners.test.tsx
+ * @description Server mode, the sidebar workspace list for an analyst: every
+ * user's workspaces, grouped under their owner (with their avatar, else an
+ * initial; 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"),
+    owner_display_name: "Bob Nguyen",
+    owner_avatar_at: "t1",
+  } as Lane,
+  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: [] })) },
+      users: {
+        avatarUrl: (id: number, at?: string | null) =>
+          at ? `/api/users/${id}/avatar?v=${at}` : null,
+      },
+      me: { avatarUrl: () => null },
+      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("names an owner by their display name when they set one", async () => {
+    renderTree();
+    await screen.findByTestId("workspace-row-1");
+    expect(screen.getByTestId("workspace-owner-3")).toHaveTextContent("Bob Nguyen");
+    expect(screen.getByTestId("workspace-owner-3")).not.toHaveTextContent("bob");
+    // Bob set a picture: shown beside the name; Ana did not: her initial.
+    expect(
+      within(screen.getByTestId("workspace-owner-3"))
+        .getByTestId("user-avatar-img")
+        .getAttribute("src")
+    ).toBe("/api/users/3/avatar?v=t1");
+    expect(
+      within(screen.getByTestId("workspace-owner-2")).getByTestId("user-avatar-initials")
+    ).toHaveTextContent("a");
+    expect(screen.getByTestId("workspace-owner-1")).toHaveTextContent("admin");
+  });
+
+  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

@@ -154,7 +154,12 @@ describe("WorkspaceTree", () => {
     expect(within(list).getByText("Live one")).toBeInTheDocument();
     // Its OWN sessions only — never the rest of its folder.
     expect(api.sessions.list).toHaveBeenCalledTimes(1);
-    expect(api.sessions.list).toHaveBeenCalledWith({ lane: 1, archived: false, limit: 6 });
+    expect(api.sessions.list).toHaveBeenCalledWith({
+      lane: 1,
+      archived: false,
+      pinnedFirst: true,
+      limit: 6,
+    });
     expect(JSON.parse(localStorage.getItem("agenthub.sidebar.projects")!).expanded).toEqual({
       "1": true,
     });
@@ -175,11 +180,21 @@ describe("WorkspaceTree", () => {
     expect(within(list).getAllByTestId(/^workspace-session-s-\d+$/)).toHaveLength(6);
     expect(screen.getByTestId("workspace-sessions-more-1")).toHaveTextContent("See all (3 more)");
     await user.click(screen.getByTestId("workspace-sessions-more-1"));
-    expect(api.sessions.list).toHaveBeenLastCalledWith({ lane: 1, archived: false, limit: 9 });
+    expect(api.sessions.list).toHaveBeenLastCalledWith({
+      lane: 1,
+      archived: false,
+      pinnedFirst: true,
+      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(api.sessions.list).toHaveBeenLastCalledWith({
+      lane: 1,
+      archived: false,
+      pinnedFirst: true,
+      limit: 6,
+    });
     expect(await screen.findByTestId("workspace-sessions-more-1")).toBeInTheDocument();
     expect(screen.queryByTestId("workspace-sessions-less-1")).toBeNull();
   });
@@ -197,6 +212,38 @@ describe("WorkspaceTree", () => {
     expect(api.sessions.patch).toHaveBeenCalledWith("s-live", { archived: true });
   });
 
+  it("pins a session above the live ones, and unpins it from its row or menu", async () => {
+    vi.mocked(api.sessions.list).mockImplementation(async () => ({
+      sessions: [
+        session("s-live", "Live one"),
+        { ...session("s-old", "Old one"), pinned_at: "2026-10-01T00:00:00Z" } as Session,
+      ],
+      total: 2,
+      limit: 20,
+      offset: 0,
+    }));
+    const user = userEvent.setup();
+    renderTree();
+    await user.click(await screen.findByTestId("workspace-toggle-1"));
+    const list = await screen.findByTestId("workspace-sessions-1");
+    await screen.findByTestId("workspace-session-pinned-s-old");
+    expect(
+      within(list)
+        .getAllByTestId(/^workspace-session-s-/)
+        .map((el) => el.dataset.testid)
+    ).toEqual(["workspace-session-s-old", "workspace-session-s-live"]);
+    await user.click(screen.getByTestId("workspace-session-pin-s-old"));
+    expect(api.sessions.patch).toHaveBeenCalledWith("s-old", { pinned: false });
+    await user.click(screen.getByTestId("workspace-session-pin-s-live"));
+    expect(api.sessions.patch).toHaveBeenCalledWith("s-live", { pinned: true });
+    await user.pointer({
+      keys: "[MouseRight]",
+      target: screen.getByTestId("workspace-session-s-old"),
+    });
+    await user.click(within(screen.getByTestId("session-menu-s-old")).getByText("Unpin"));
+    expect(api.sessions.patch).toHaveBeenLastCalledWith("s-old", { pinned: false });
+  });
+
   it("right-click on a session opens its menu: split, rename, archive, close its tab", async () => {
     const user = userEvent.setup();
     renderTree();
@@ -207,7 +254,7 @@ describe("WorkspaceTree", () => {
     let menu = screen.getByTestId("session-menu-s-old");
     // Ended: no pane to split or close.
     expect(within(menu).queryByText("Open in split")).toBeNull();
-    expect(within(menu).queryByText("Close tab (stops its session)")).toBeNull();
+    expect(within(menu).queryByText("Close tab (stops and archives its session)")).toBeNull();
     await user.click(within(menu).getByText("Rename"));
     expect(screen.queryByTestId("session-menu-s-old")).toBeNull();
     expect(screen.getByTestId("workspace-session-rename-s-old")).toBeInTheDocument();
@@ -224,11 +271,17 @@ describe("WorkspaceTree", () => {
     await user.click(within(screen.getByTestId("session-menu-s-live")).getByText("Archive"));
     expect(api.sessions.patch).toHaveBeenCalledWith("s-live", { archived: true });
 
+    await right(screen.getByTestId("workspace-session-s-live"));
+    await user.click(screen.getByTestId("session-menu-sleep"));
+    expect(api.run.kill).toHaveBeenCalledWith("agenthub-lane-1-2", { archive: false });
+
     await right(screen.getByTestId("workspace-session-s-live"));
     await user.click(
-      within(screen.getByTestId("session-menu-s-live")).getByText("Close tab (stops its session)")
+      within(screen.getByTestId("session-menu-s-live")).getByText(
+        "Close tab (stops and archives its session)"
+      )
     );
-    expect(api.run.kill).toHaveBeenCalledWith("agenthub-lane-1-2");
+    expect(api.run.kill).toHaveBeenCalledWith("agenthub-lane-1-2", { archive: true });
   });
 
   it("archiving a worktree session removes its worktree first, after asking", async () => {

client/src/components/admin/ServerPanel.tsx

@@ -0,0 +1,417 @@
+/**
+ * @file ServerPanel.tsx
+ * @description The Administration page's Server tab: the machine AgentHub
+ * runs on — hostname, OS, uptime, CPU and its load, memory and swap, every
+ * real disk (HDD/SSD, how full), any NVIDIA GPU — and each user's live share
+ * of it (`GET /api/host`, server/lib/host-stats.js): CPU % of the whole
+ * machine, resident memory, process count, the busiest processes by name, and
+ * the disk their home takes (`GET /api/users/storage`, as a share of the disk
+ * that holds the homes). Re-read every `POLL_MS` while shown; Refresh re-reads
+ * at once. Read-only — the only action here is the members' tmux card
+ * (`MemberTmuxCard`, an admin's restart).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { Fragment, useCallback, useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  AlertCircle,
+  ChevronDown,
+  ChevronRight,
+  Cpu,
+  HardDrive,
+  MemoryStick,
+  MonitorCog,
+  RefreshCw,
+  Server,
+} from "lucide-react";
+import {
+  api,
+  type HostStats,
+  type HostUsageGroup,
+  type ServerUserUsage,
+  type UserStorage,
+} from "../../lib/api";
+import { formatBytes } from "../../lib/format";
+import { useSpin } from "../../hooks/useSpin";
+import { StatCard } from "../StatCard";
+import { UserAvatar } from "../users/UserAvatar";
+import { MemberTmuxCard } from "../users/MemberTmuxCard";
+
+const POLL_MS = 5000;
+
+const pct = (part: number, whole: number) => (whole > 0 ? (part / whole) * 100 : 0);
+const fmtPct = (n: number) => `${n < 10 ? n.toFixed(1) : Math.round(n)}%`;
+
+/** A thin bar, amber past 75 %, red past 90 %. */
+function Meter({ value, label }: { value: number; label: string }) {
+  const v = Math.max(0, Math.min(100, value));
+  const tone = v >= 90 ? "bg-status-danger" : v >= 75 ? "bg-status-warning" : "bg-accent-solid";
+  return (
+    <div
+      role="meter"
+      aria-label={label}
+      aria-valuenow={Math.round(v)}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      className="h-1.5 w-full rounded-full bg-surface-4 overflow-hidden"
+    >
+      <div className={`h-full rounded-full ${tone}`} style={{ width: `${v}%` }} />
+    </div>
+  );
+}
+
+function uptimeText(t: (k: string, o?: Record<string, unknown>) => string, sec: number) {
+  const d = Math.floor(sec / 86400);
+  const h = Math.floor((sec % 86400) / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  return d > 0 ? t("server.uptimeDays", { d, h }) : t("server.uptimeHours", { h, m });
+}
+
+export function ServerPanel({ isAdmin }: { isAdmin: boolean }) {
+  const { t } = useTranslation("admin");
+  const [stats, setStats] = useState<HostStats | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [users, setUsers] = useState<ServerUserUsage[] | null>(null);
+  const [storage, setStorage] = useState<Record<string, UserStorage> | null>(null);
+  const [open, setOpen] = useState<Set<string>>(new Set());
+
+  const load = useCallback(
+    () =>
+      api.host
+        .stats()
+        .then((s) => {
+          setStats(s);
+          setError(null);
+        })
+        .catch((e: Error) => setError(e.message)),
+    []
+  );
+  const [spinning, refresh] = useSpin(load);
+
+  useEffect(() => {
+    void load();
+    const id = setInterval(() => {
+      if (document.visibilityState === "visible") void load();
+    }, POLL_MS);
+    return () => clearInterval(id);
+  }, [load]);
+
+  // Names, pictures and home sizes: read once, they change slowly.
+  useEffect(() => {
+    api.users
+      .list()
+      .then((r) => setUsers(r.users))
+      .catch(() => setUsers([]));
+    api.users
+      .storage()
+      .then((r) => setStorage(r.storage))
+      .catch(() => setStorage({}));
+  }, []);
+
+  const byId = new Map((users ?? []).map((u) => [u.id, u]));
+  const homesDisk = stats?.disks.find((d) => d.mount === stats.homesMount) ?? null;
+  const loading = !stats && !error;
+  const mem = stats?.memory;
+  const toggle = (key: string) =>
+    setOpen((s) => {
+      const n = new Set(s);
+      if (n.has(key)) n.delete(key);
+      else n.add(key);
+      return n;
+    });
+
+  const groupName = (g: HostUsageGroup) => {
+    if (g.kind === "host") return t("server.hostGroup");
+    if (g.kind === "system") return t("server.systemGroup");
+    const u = g.userId != null ? byId.get(g.userId) : undefined;
+    return u?.displayName || g.username || "";
+  };
+  const th = "px-5 py-3 text-[11px] font-semibold text-fg-muted uppercase tracking-wider";
+
+  return (
+    <div className="space-y-6" data-testid="server-panel">
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div className="min-w-0">
+          <h2 className="flex items-center gap-2 text-sm font-semibold text-fg-primary">
+            <Server className="w-4 h-4 text-accent" />
+            <span className="truncate">{stats?.hostname ?? t("server.title")}</span>
+          </h2>
+          {stats && (
+            <p className="mt-0.5 text-xs text-fg-muted">
+              {[stats.os.distro ?? stats.os.platform, stats.os.release, stats.os.arch].join(" · ")}
+              {" · "}
+              {t("server.uptime", { v: uptimeText(t, stats.uptime) })}
+            </p>
+          )}
+        </div>
+        <button
+          type="button"
+          onClick={refresh}
+          disabled={spinning}
+          aria-busy={spinning}
+          className="btn-ghost"
+        >
+          <RefreshCw className={`w-4 h-4 ${spinning ? "animate-spin" : ""}`} />{" "}
+          {t("common:refresh")}
+        </button>
+      </div>
+
+      {error && (
+        <div
+          role="alert"
+          className="card flex flex-wrap items-center gap-3 p-3 border-status-danger/40 text-sm text-status-danger"
+        >
+          <AlertCircle className="w-4 h-4 flex-shrink-0" />
+          <span className="flex-1 min-w-0">{error}</span>
+          <button type="button" onClick={refresh} className="btn-ghost text-xs">
+            {t("common:retry")}
+          </button>
+        </div>
+      )}
+
+      <div className="grid grid-cols-2 lg:grid-cols-4 gap-4">
+        <StatCard
+          label={t("server.cpu")}
+          value={stats?.usage ? fmtPct(stats.usage.cpu) : "—"}
+          icon={Cpu}
+          trend={
+            stats
+              ? t("server.cores", {
+                  n: stats.cpu.cores,
+                  load: stats.cpu.load.map((l) => l.toFixed(2)).join(" "),
+                })
+              : undefined
+          }
+          raw={stats?.cpu.model ?? undefined}
+          help={t("server.cpuHelp")}
+          loading={loading}
+        />
+        <StatCard
+          label={t("server.memory")}
+          value={mem ? fmtPct(pct(mem.used, mem.total)) : "—"}
+          icon={MemoryStick}
+          trend={mem ? `${formatBytes(mem.used)} / ${formatBytes(mem.total)}` : undefined}
+          loading={loading}
+        />
+        <StatCard
+          label={t("server.swap")}
+          value={mem && mem.swapTotal ? fmtPct(pct(mem.swapUsed, mem.swapTotal)) : "—"}
+          icon={MonitorCog}
+          trend={mem ? `${formatBytes(mem.swapUsed)} / ${formatBytes(mem.swapTotal)}` : undefined}
+          loading={loading}
+        />
+        <StatCard
+          label={t("server.homesDisk")}
+          value={homesDisk ? fmtPct(pct(homesDisk.used, homesDisk.total)) : "—"}
+          icon={HardDrive}
+          trend={
+            homesDisk
+              ? `${formatBytes(homesDisk.free)} ${t("server.free")} · ${homesDisk.mount}`
+              : undefined
+          }
+          help={t("server.homesDiskHelp")}
+          loading={loading}
+        />
+      </div>
+
+      <div className="card overflow-x-auto">
+        <div className="px-5 pt-4 pb-2">
+          <h3 className="text-sm font-semibold text-fg-primary">{t("server.usageTitle")}</h3>
+          <p className="text-xs text-fg-muted">
+            {t("server.usageHelp", { s: (stats?.usage?.sampleMs ?? 1000) / 1000 })}
+          </p>
+        </div>
+        {stats && !stats.usage ? (
+          <p className="px-5 pb-4 text-sm text-fg-muted">{t("server.usageUnavailable")}</p>
+        ) : (
+          <table className="w-full min-w-[760px]" data-testid="server-usage-table">
+            <thead>
+              <tr className="border-b border-border text-left">
+                <th className={th}>{t("server.who")}</th>
+                <th className={`${th} w-[18%]`}>{t("server.cpu")}</th>
+                <th className={`${th} w-[22%]`}>{t("server.memory")}</th>
+                <th className={`${th} text-right`}>{t("server.processes")}</th>
+                <th className={`${th} w-[18%]`}>{t("server.home")}</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-border">
+              {loading && (
+                <tr>
+                  <td colSpan={5} className="px-5 py-6 text-sm text-fg-muted">
+                    {t("server.sampling")}
+                  </td>
+                </tr>
+              )}
+              {stats?.usage?.groups.map((g) => {
+                const u = g.userId != null ? byId.get(g.userId) : undefined;
+                const home = g.userId != null && storage ? storage[g.userId] : undefined;
+                const isOpen = open.has(g.key);
+                const name = groupName(g);
+                return (
+                  <Fragment key={g.key}>
+                    <tr className="hover:bg-surface-4/40 transition-colors">
+                      <td className="px-5 py-3">
+                        <button
+                          type="button"
+                          onClick={() => toggle(g.key)}
+                          disabled={!g.top.length}
+                          aria-expanded={isOpen}
+                          className="flex items-center gap-2 text-left disabled:cursor-default"
+                        >
+                          {g.top.length ? (
+                            isOpen ? (
+                              <ChevronDown className="w-3.5 h-3.5 text-fg-muted" />
+                            ) : (
+                              <ChevronRight className="w-3.5 h-3.5 text-fg-muted" />
+                            )
+                          ) : (
+                            <span className="w-3.5" />
+                          )}
+                          {g.kind === "user" ? (
+                            <UserAvatar
+                              name={name}
+                              avatarAt={u?.avatarAt}
+                              userId={g.userId}
+                              className="h-6 w-6 text-[10px]"
+                            />
+                          ) : (
+                            <span className="flex h-6 w-6 items-center justify-center rounded-full bg-surface-4">
+                              <Server className="w-3.5 h-3.5 text-fg-muted" />
+                            </span>
+                          )}
+                          <span className="min-w-0">
+                            <span className="block text-sm text-fg-primary truncate">{name}</span>
+                            {g.kind === "user" && u?.displayName && (
+                              <span className="block text-[11px] text-fg-muted">{g.username}</span>
+                            )}
+                          </span>
+                        </button>
+                      </td>
+                      <td className="px-5 py-3">
+                        <div className="text-sm text-fg-primary tabular-nums">{fmtPct(g.cpu)}</div>
+                        <Meter value={g.cpu} label={`${name} ${t("server.cpu")}`} />
+                      </td>
+                      <td className="px-5 py-3">
+                        <div className="text-sm text-fg-primary tabular-nums">
+                          {formatBytes(g.memory)}{" "}
+                          <span className="text-fg-muted">({fmtPct(g.memoryPercent)})</span>
+                        </div>
+                        <Meter value={g.memoryPercent} label={`${name} ${t("server.memory")}`} />
+                      </td>
+                      <td className="px-5 py-3 text-right text-sm text-fg-secondary tabular-nums">
+                        {g.processes}
+                      </td>
+                      <td className="px-5 py-3">
+                        {home ? (
+                          <>
+                            <div className="text-sm text-fg-primary tabular-nums">
+                              {formatBytes(home.bytes)}
+                              {homesDisk && (
+                                <span className="text-fg-muted">
+                                  {" "}
+                                  ({fmtPct(pct(home.bytes, homesDisk.total))})
+                                </span>
+                              )}
+                            </div>
+                            {homesDisk && (
+                              <Meter
+                                value={pct(home.bytes, homesDisk.total)}
+                                label={`${name} ${t("server.home")}`}
+                              />
+                            )}
+                          </>
+                        ) : (
+                          <span className="text-sm text-fg-muted">—</span>
+                        )}
+                      </td>
+                    </tr>
+                    {isOpen &&
+                      g.top.map((p) => (
+                        <tr key={`${g.key}:${p.pid}`} className="bg-surface-2/40">
+                          <td className="pl-14 pr-5 py-1.5 text-xs text-fg-secondary font-mono truncate">
+                            {p.name} <span className="text-fg-muted">#{p.pid}</span>
+                          </td>
+                          <td className="px-5 py-1.5 text-xs text-fg-secondary tabular-nums">
+                            {fmtPct(p.cpu)}
+                          </td>
+                          <td className="px-5 py-1.5 text-xs text-fg-secondary tabular-nums">
+                            {formatBytes(p.memory)}
+                          </td>
+                          <td colSpan={2} />
+                        </tr>
+                      ))}
+                  </Fragment>
+                );
+              })}
+            </tbody>
+          </table>
+        )}
+      </div>
+
+      {stats && stats.disks.length > 0 && (
+        <div className="card overflow-x-auto">
+          <h3 className="px-5 pt-4 pb-2 text-sm font-semibold text-fg-primary">
+            {t("server.disks")}
+          </h3>
+          <table className="w-full min-w-[640px]" data-testid="server-disks-table">
+            <thead>
+              <tr className="border-b border-border text-left">
+                <th className={th}>{t("server.mount")}</th>
+                <th className={th}>{t("server.device")}</th>
+                <th className={`${th} w-[30%]`}>{t("server.used")}</th>
+                <th className={`${th} text-right`}>{t("server.free")}</th>
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-border">
+              {stats.disks.map((d) => (
+                <tr key={d.device}>
+                  <td className="px-5 py-3 text-sm text-fg-primary">
+                    <span className="font-mono">{d.mount}</span>
+                    {d.mount === stats.homesMount && (
+                      <span className="badge ml-2 py-0 text-[10px]">{t("server.homesBadge")}</span>
+                    )}
+                  </td>
+                  <td className="px-5 py-3 text-xs text-fg-secondary">
+                    <span className="font-mono">{d.device}</span> · {d.type}
+                    {d.kind && <span className="badge ml-2 py-0 text-[10px]">{d.kind}</span>}
+                  </td>
+                  <td className="px-5 py-3">
+                    <div className="text-sm text-fg-primary tabular-nums">
+                      {formatBytes(d.used)} / {formatBytes(d.total)}{" "}
+                      <span className="text-fg-muted">({fmtPct(pct(d.used, d.total))})</span>
+                    </div>
+                    <Meter value={pct(d.used, d.total)} label={d.mount} />
+                  </td>
+                  <td className="px-5 py-3 text-right text-sm text-fg-secondary tabular-nums">
+                    {formatBytes(d.free)}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+
+      {stats && stats.gpus.length > 0 && (
+        <div className="card p-5 space-y-3">
+          <h3 className="text-sm font-semibold text-fg-primary">{t("server.gpus")}</h3>
+          {stats.gpus.map((g, i) => (
+            <div key={i} className="space-y-1">
+              <div className="flex justify-between text-sm">
+                <span className="text-fg-primary">{g.name}</span>
+                <span className="text-fg-muted tabular-nums">
+                  {fmtPct(g.utilization)} · {formatBytes(g.memoryUsed)} /{" "}
+                  {formatBytes(g.memoryTotal)}
+                </span>
+              </div>
+              <Meter value={g.utilization} label={g.name} />
+            </div>
+          ))}
+        </div>
+      )}
+
+      <MemberTmuxCard isAdmin={isAdmin} />
+    </div>
+  );
+}

client/src/components/artifacts/ArtifactAddPanels.tsx

@@ -0,0 +1,928 @@
+/**
+ * @file ArtifactAddPanels.tsx
+ * @description The Artifacts page's Add dialogs for a skill, a plugin and an
+ * uploaded file (server/lib/artifacts.js):
+ * - `SkillAddPanel` — three ways to make a skill: **Upload** (one Markdown
+ *   file that becomes SKILL.md, several files, a whole folder — picked or
+ *   dropped — or a .zip/.skill; an upload holding several skills makes one
+ *   artifact each), **Write** (name, description, instructions) and
+ *   **Existing** (a folder in the user's ~/.claude/skills or a workspace's
+ *   .claude/skills). The user names the skill; the name is previewed as the
+ *   folder and `/command` it installs as (`skillSlug`, the server's rule).
+ * - `PluginAddPanel` — paste a marketplace link (a git https link, a forge
+ *   web link, `owner/repo` or a marketplace.json link), read its plugin list
+ *   and tick the ones to add; or type `name@marketplace` by hand, which is
+ *   also where a link the server cannot read (ssh, a private repo) ends up.
+ * - `FileUploadPanel` — one file from the user's computer (≤ 25 MB).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useMemo, useRef, useState, type DragEvent } from "react";
+import { useTranslation } from "react-i18next";
+import { FileText, FolderOpen, Package, Sparkles, Upload, X } from "lucide-react";
+import { api, type MarketplaceInfo } from "../../lib/api";
+import type { Lane } from "../../lib/types";
+import { toast } from "../../lib/toast";
+
+const field = "w-full rounded border border-border bg-surface-1 px-2 py-1 text-sm text-fg-primary";
+const label = "block text-[11px] font-medium text-fg-secondary";
+const hint = "text-[11px] text-fg-muted";
+
+/** The server's skill folder rule (server/lib/artifacts.js `skillSlug`). */
+export function skillSlug(text: string): string {
+  return text
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/đ/g, "d")
+    .replace(/Đ/g, "D")
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^[-._]+|-+$/g, "")
+    .slice(0, 100);
+}
+
+/** `field:` of a Markdown file's frontmatter, or "". */
+export function frontmatterField(text: string, name: string): string {
+  const fm = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!fm) return "";
+  const m = new RegExp(`^${name}:\\s*(.*)$`, "m").exec(fm[1] ?? "");
+  return (m?.[1] ?? "").trim().replace(/^(["'])(.*)\1$/, "$2");
+}
+
+type Picked = { file: File; path: string };
+
+/** A small file's text ("" on failure), only to prefill the name/description. */
+function readText(file: File): Promise<string> {
+  if (file.size > 1024 * 1024) return Promise.resolve("");
+  return new Promise((ok) => {
+    const r = new FileReader();
+    r.onload = () => ok(typeof r.result === "string" ? r.result : "");
+    r.onerror = () => ok("");
+    r.readAsText(file);
+  });
+}
+
+const JUNK = /(^|\/)(__MACOSX|\.DS_Store|Thumbs\.db|desktop\.ini|\.git|node_modules)(\/|$)/;
+const isSkillMd = (p: string) => /(^|\/)skill\.md$/i.test(p);
+const isArchive = (p: string) => /\.(zip|skill)$/i.test(p);
+const isText = (p: string) => /\.(md|markdown|txt)$/i.test(p);
+
+/** Every file under what was dropped, folders walked (webkitGetAsEntry). */
+async function droppedFiles(e: DragEvent): Promise<Picked[]> {
+  const items = Array.from(e.dataTransfer.items || []);
+  const entries = items
+    .map((i) => (i.webkitGetAsEntry ? i.webkitGetAsEntry() : null))
+    .filter((x): x is FileSystemEntry => !!x);
+  if (!entries.length) {
+    return Array.from(e.dataTransfer.files).map((file) => ({ file, path: file.name }));
+  }
+  const out: Picked[] = [];
+  const walk = async (entry: FileSystemEntry, prefix: string): Promise<void> => {
+    if (entry.isFile) {
+      const file = await new Promise<File>((ok, fail) =>
+        (entry as FileSystemFileEntry).file(ok, fail)
+      );
+      out.push({ file, path: prefix + entry.name });
+      return;
+    }
+    const reader = (entry as FileSystemDirectoryEntry).createReader();
+    // readEntries answers in batches until an empty one.
+    for (;;) {
+      const batch = await new Promise<FileSystemEntry[]>((ok, fail) =>
+        reader.readEntries(ok, fail)
+      );
+      if (!batch.length) break;
+      for (const child of batch) await walk(child, `${prefix}${entry.name}/`);
+    }
+  };
+  for (const entry of entries) await walk(entry, "");
+  return out;
+}
+
+/** What an upload will make, guessed the way the server decides it. */
+function describeUpload(files: Picked[]): {
+  kind: "none" | "single-md" | "archive" | "one" | "many" | "no-skill-md";
+  count: number;
+  folder: string;
+} {
+  const real = files.filter((f) => !JUNK.test(f.path));
+  if (!real.length) return { kind: "none", count: 0, folder: "" };
+  if (real.length === 1 && isArchive(real[0]!.path))
+    return { kind: "archive", count: 0, folder: "" };
+  const roots = [
+    ...new Set(
+      real.filter((f) => isSkillMd(f.path)).map((f) => f.path.split("/").slice(0, -1).join("/"))
+    ),
+  ].sort((a, b) => a.length - b.length);
+  const under = (dir: string, p: string) => dir === "" || p === dir || p.startsWith(`${dir}/`);
+  const top = roots.filter((r, i) => !roots.slice(0, i).some((o) => under(o, r)));
+  if (!top.length) {
+    return real.length === 1 && isText(real[0]!.path)
+      ? { kind: "single-md", count: 1, folder: "" }
+      : { kind: "no-skill-md", count: 0, folder: "" };
+  }
+  if (top.length === 1) return { kind: "one", count: 1, folder: top[0]!.split("/").pop() ?? "" };
+  return { kind: "many", count: top.length, folder: "" };
+}
+
+function Tabs<T extends string>({
+  value,
+  options,
+  onChange,
+}: {
+  value: T;
+  options: { id: T; label: string }[];
+  onChange: (v: T) => void;
+}) {
+  return (
+    <div role="tablist" className="flex rounded border border-border bg-surface-2 p-0.5">
+      {options.map((o) => (
+        <button
+          key={o.id}
+          type="button"
+          role="tab"
+          aria-selected={value === o.id}
+          onClick={() => onChange(o.id)}
+          className={`flex-1 rounded px-2 py-1 text-xs ${
+            value === o.id
+              ? "bg-accent-solid text-white"
+              : "text-fg-secondary hover:bg-surface-3 hover:text-fg-primary"
+          }`}
+        >
+          {o.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/** The name field with the folder/command it becomes. */
+function SkillNameField({
+  value,
+  onChange,
+  disabled,
+  required,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  disabled?: boolean;
+  required?: boolean;
+}) {
+  const { t } = useTranslation("artifacts");
+  const slug = skillSlug(value);
+  return (
+    <div className="space-y-0.5">
+      <label className={label}>
+        {t("skill.name")}
+        {required ? " *" : ""}
+        <input
+          className={`${field} mt-0.5`}
+          value={value}
+          disabled={disabled}
+          placeholder="release-notes"
+          onChange={(e) => onChange(e.target.value)}
+        />
+      </label>
+      {value.trim() && (
+        <p className={hint} data-testid="skill-slug">
+          {slug ? t("skill.slugHint", { slug }) : t("skill.slugBad")}
+        </p>
+      )}
+    </div>
+  );
+}
+
+// ── Skill ─────────────────────────────────────────────────────────────────
+
+export function SkillAddPanel({
+  lanes,
+  onAdded,
+  onClose,
+}: {
+  lanes: Lane[];
+  onAdded: () => void;
+  onClose: () => void;
+}) {
+  const { t } = useTranslation("artifacts");
+  const [mode, setMode] = useState<"upload" | "write" | "existing">("upload");
+  const [busy, setBusy] = useState(false);
+  const [name, setName] = useState("");
+  const [nameTouched, setNameTouched] = useState(false);
+  const [description, setDescription] = useState("");
+  const [descTouched, setDescTouched] = useState(false);
+  const [title, setTitle] = useState("");
+  const [content, setContent] = useState("");
+  const [files, setFiles] = useState<Picked[]>([]);
+  const [dragging, setDragging] = useState(false);
+  const [laneId, setLaneId] = useState<number | null>(null);
+  const [skills, setSkills] = useState<{ name: string; from: "user" | "workspace" }[] | null>(null);
+  const fileInput = useRef<HTMLInputElement>(null);
+  const folderInput = useRef<HTMLInputElement>(null);
+
+  // `webkitdirectory` is not in React's typings.
+  useEffect(() => {
+    folderInput.current?.setAttribute("webkitdirectory", "");
+  }, [mode]);
+
+  useEffect(() => {
+    if (mode !== "existing") return;
+    api.artifacts
+      .skills(laneId ?? undefined)
+      .then((r) => setSkills(r.items))
+      .catch(() => setSkills([]));
+  }, [mode, laneId]);
+
+  const shape = useMemo(() => describeUpload(files), [files]);
+
+  // Fill the name and description from what was picked, unless typed.
+  useEffect(() => {
+    if (!files.length) return;
+    const md =
+      files.find((f) => isSkillMd(f.path) && !JUNK.test(f.path)) ??
+      (shape.kind === "single-md" ? files.find((f) => !JUNK.test(f.path)) : undefined);
+    const stem = (p: string) => (p.split("/").pop() ?? "").replace(/\.[^.]+$/, "");
+    let live = true;
+    void (async () => {
+      const text = md ? await readText(md.file) : "";
+      if (!live) return;
+      const fmName = frontmatterField(text, "name");
+      const fmDesc = frontmatterField(text, "description");
+      if (!nameTouched) {
+        const guess =
+          shape.kind === "single-md"
+            ? fmName || stem(md?.path ?? "")
+            : shape.kind === "one"
+              ? fmName || shape.folder
+              : shape.kind === "archive"
+                ? stem(files[0]!.path)
+                : "";
+        setName(guess);
+      }
+      if (!descTouched && fmDesc) setDescription(fmDesc);
+    })();
+    return () => {
+      live = false;
+    };
+    // Refill only when the pick changes, never on a typed name.
+  }, [files, shape]);
+
+  const pick = (list: FileList | null) => {
+    if (!list?.length) return;
+    setFiles(
+      Array.from(list).map((file) => ({
+        file,
+        path: (file as File & { webkitRelativePath?: string }).webkitRelativePath || file.name,
+      }))
+    );
+  };
+
+  const run = async (fn: () => Promise<number>) => {
+    setBusy(true);
+    try {
+      const n = await fn();
+      toast.success(n > 1 ? t("skill.addedMany", { count: n }) : t("added"));
+      onAdded();
+      onClose();
+    } catch (err) {
+      toast.error(err);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const many = shape.kind === "many";
+  const total = files.reduce((n, f) => n + f.file.size, 0);
+  const meta = (
+    <>
+      <label className={label}>
+        {t("skill.description")}
+        <textarea
+          className={`${field} mt-0.5`}
+          rows={2}
+          value={description}
+          disabled={many}
+          placeholder={t("skill.descriptionHint")}
+          onChange={(e) => {
+            setDescTouched(true);
+            setDescription(e.target.value);
+          }}
+        />
+      </label>
+      <label className={label}>
+        {t("form.title")}
+        <input
+          className={`${field} mt-0.5`}
+          value={title}
+          disabled={many}
+          onChange={(e) => setTitle(e.target.value)}
+        />
+      </label>
+    </>
+  );
+
+  return (
+    <div className="space-y-3">
+      <Tabs
+        value={mode}
+        onChange={setMode}
+        options={[
+          { id: "upload", label: t("skill.tab.upload") },
+          { id: "write", label: t("skill.tab.write") },
+          { id: "existing", label: t("skill.tab.existing") },
+        ]}
+      />
+
+      {mode === "upload" && (
+        <form
+          className="space-y-2"
+          onSubmit={(e) => {
+            e.preventDefault();
+            void run(async () => {
+              const r = await api.artifacts.uploadSkills(files, {
+                name: many ? undefined : name.trim(),
+                description: many ? undefined : description.trim(),
+                title: many ? undefined : title.trim(),
+              });
+              return r.items.length;
+            });
+          }}
+        >
+          <div
+            data-testid="skill-drop"
+            onDragOver={(e) => {
+              e.preventDefault();
+              setDragging(true);
+            }}
+            onDragLeave={() => setDragging(false)}
+            onDrop={(e) => {
+              e.preventDefault();
+              setDragging(false);
+              void droppedFiles(e).then((list) => list.length && setFiles(list));
+            }}
+            className={`rounded-lg border border-dashed p-4 text-center ${
+              dragging ? "border-accent bg-accent/10" : "border-border"
+            }`}
+          >
+            <Upload className="mx-auto mb-1 h-5 w-5 text-fg-muted" />
+            <p className="text-xs text-fg-secondary">{t("skill.dropHint")}</p>
+            <div className="mt-2 flex flex-wrap justify-center gap-2">
+              <button
+                type="button"
+                className="btn-ghost text-xs"
+                onClick={() => fileInput.current?.click()}
+              >
+                <FileText className="h-3.5 w-3.5" /> {t("skill.pickFiles")}
+              </button>
+              <button
+                type="button"
+                className="btn-ghost text-xs"
+                onClick={() => folderInput.current?.click()}
+              >
+                <FolderOpen className="h-3.5 w-3.5" /> {t("skill.pickFolder")}
+              </button>
+            </div>
+            <input
+              ref={fileInput}
+              type="file"
+              multiple
+              hidden
+              data-testid="skill-files"
+              onChange={(e) => {
+                pick(e.target.files);
+                e.target.value = "";
+              }}
+            />
+            <input
+              ref={folderInput}
+              type="file"
+              multiple
+              hidden
+              data-testid="skill-folder"
+              onChange={(e) => {
+                pick(e.target.files);
+                e.target.value = "";
+              }}
+            />
+          </div>
+
+          {files.length > 0 && (
+            <div className="rounded border border-border bg-surface-2 p-2">
+              <div className="mb-1 flex items-center gap-2">
+                <p className="flex-1 text-xs text-fg-primary" data-testid="skill-shape">
+                  {t(`skill.shape.${shape.kind}`, { count: shape.count })}
+                </p>
+                <span className={hint}>
+                  {t("files", { count: files.length })} · {Math.ceil(total / 1024)} KB
+                </span>
+                <button
+                  type="button"
+                  aria-label={t("skill.clear")}
+                  className="text-fg-muted hover:text-fg-primary"
+                  onClick={() => {
+                    setFiles([]);
+                    setNameTouched(false);
+                    setDescTouched(false);
+                  }}
+                >
+                  <X className="h-3.5 w-3.5" />
+                </button>
+              </div>
+              <ul className="max-h-28 overflow-auto font-mono text-[11px] text-fg-secondary">
+                {files.slice(0, 200).map((f) => (
+                  <li
+                    key={f.path}
+                    className={`truncate ${JUNK.test(f.path) ? "line-through opacity-50" : ""}`}
+                  >
+                    {f.path}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          {many ? (
+            <p className={hint}>{t("skill.manyHint")}</p>
+          ) : (
+            <SkillNameField
+              value={name}
+              onChange={(v) => {
+                setNameTouched(true);
+                setName(v);
+              }}
+              required={shape.kind === "single-md"}
+            />
+          )}
+          {meta}
+          <div className="flex justify-end">
+            <button
+              type="submit"
+              className="btn-primary text-sm"
+              disabled={
+                busy ||
+                !files.length ||
+                shape.kind === "no-skill-md" ||
+                (shape.kind === "single-md" && !skillSlug(name))
+              }
+            >
+              {busy ? t("skill.uploading") : t("form.save")}
+            </button>
+          </div>
+        </form>
+      )}
+
+      {mode === "write" && (
+        <form
+          className="space-y-2"
+          onSubmit={(e) => {
+            e.preventDefault();
+            void run(async () => {
+              await api.artifacts.writeSkill({
+                name: name.trim(),
+                description: description.trim(),
+                content,
+                title: title.trim() || undefined,
+              });
+              return 1;
+            });
+          }}
+        >
+          <SkillNameField value={name} onChange={setName} required />
+          <label className={label}>
+            {t("skill.description")} *
+            <textarea
+              className={`${field} mt-0.5`}
+              rows={2}
+              value={description}
+              placeholder={t("skill.descriptionHint")}
+              onChange={(e) => setDescription(e.target.value)}
+            />
+          </label>
+          <label className={label}>
+            {t("skill.content")} *
+            <textarea
+              className={`${field} mt-0.5 font-mono text-xs`}
+              rows={10}
+              value={content}
+              placeholder={t("skill.contentHint")}
+              onChange={(e) => setContent(e.target.value)}
+            />
+          </label>
+          <label className={label}>
+            {t("form.title")}
+            <input
+              className={`${field} mt-0.5`}
+              value={title}
+              onChange={(e) => setTitle(e.target.value)}
+            />
+          </label>
+          <div className="flex justify-end">
+            <button
+              type="submit"
+              className="btn-primary text-sm"
+              disabled={
+                busy ||
+                !skillSlug(name) ||
+                !content.trim() ||
+                (!description.trim() && !frontmatterField(content, "description"))
+              }
+            >
+              {t("form.save")}
+            </button>
+          </div>
+        </form>
+      )}
+
+      {mode === "existing" && (
+        <div className="space-y-2">
+          <select
+            className={field}
+            aria-label={t("form.workspace")}
+            value={laneId ?? ""}
+            onChange={(e) => setLaneId(e.target.value ? Number(e.target.value) : null)}
+          >
+            <option value="">{t("form.pickWorkspace")}</option>
+            {lanes.map((l) => (
+              <option key={l.id} value={l.id}>
+                {l.title || l.cwd}
+              </option>
+            ))}
+          </select>
+          {skills && skills.length === 0 && <p className={hint}>{t("form.noSkills")}</p>}
+          {skills && skills.length > 0 && (
+            <ul className="max-h-72 space-y-0.5 overflow-auto">
+              {skills.map((s) => (
+                <li key={`${s.from}:${s.name}`} className="flex items-center gap-2 text-xs">
+                  <Sparkles className="h-3 w-3 shrink-0 text-fg-muted" />
+                  <span className="min-w-0 flex-1 truncate text-fg-secondary">{s.name}</span>
+                  <span className="text-fg-muted">
+                    {t(s.from === "user" ? "form.fromUser" : "form.fromWorkspace")}
+                  </span>
+                  <button
+                    type="button"
+                    className="btn-ghost text-xs"
+                    disabled={busy}
+                    onClick={() =>
+                      void run(async () => {
+                        await api.artifacts.addSkill({
+                          name: s.name,
+                          ...(s.from === "workspace" && laneId ? { laneId } : {}),
+                          title: title || undefined,
+                          description: description || undefined,
+                        });
+                        return 1;
+                      })
+                    }
+                  >
+                    {t("form.save")}
+                  </button>
+                </li>
+              ))}
+            </ul>
+          )}
+          <input
+            className={field}
+            placeholder={t("form.title")}
+            aria-label={t("form.title")}
+            value={title}
+            onChange={(e) => setTitle(e.target.value)}
+          />
+          <textarea
+            className={field}
+            rows={2}
+            placeholder={t("form.description")}
+            aria-label={t("form.description")}
+            value={description}
+            onChange={(e) => setDescription(e.target.value)}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── Plugin ────────────────────────────────────────────────────────────────
+
+const MANUAL_CODES = new Set(["ENEEDLOGIN", "ESSHMARKET", "ENOTMARKET", "EMARKETFETCH"]);
+
+export function PluginAddPanel({ onAdded, onClose }: { onAdded: () => void; onClose: () => void }) {
+  const { t } = useTranslation("artifacts");
+  const [link, setLink] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [info, setInfo] = useState<MarketplaceInfo | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [picked, setPicked] = useState<Set<string>>(new Set());
+  const [have, setHave] = useState<Set<string>>(new Set());
+  const [manual, setManual] = useState(false);
+  const [key, setKey] = useState("");
+  const [market, setMarket] = useState("");
+  const [title, setTitle] = useState("");
+  const [description, setDescription] = useState("");
+
+  useEffect(() => {
+    api.artifacts
+      .list({ scope: "mine", kind: "plugin" })
+      .then((r) => setHave(new Set(r.items.map((i) => i.source ?? ""))))
+      .catch(() => setHave(new Set()));
+  }, []);
+
+  const read = async () => {
+    setBusy(true);
+    setError(null);
+    setInfo(null);
+    try {
+      const r = await api.artifacts.inspectMarket(link.trim());
+      setInfo(r);
+      setPicked(
+        new Set(
+          r.plugins
+            .filter((p) => !have.has(p.key))
+            .slice(0, 1)
+            .map((p) => p.key)
+        )
+      );
+      setMarket(r.market);
+    } catch (err) {
+      const e = err as Error & { code?: string };
+      setError(e.message);
+      if (MANUAL_CODES.has(e.code ?? "")) {
+        setManual(true);
+        setMarket(link.trim());
+      }
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const addPicked = async () => {
+    if (!info) return;
+    setBusy(true);
+    let n = 0;
+    try {
+      for (const p of info.plugins.filter((x) => picked.has(x.key))) {
+        await api.artifacts.addPlugin({
+          key: p.key,
+          market: info.market,
+          title: p.name,
+          description: p.description,
+        });
+        n++;
+      }
+      toast.success(t("plugin.addedMany", { count: n }));
+      onAdded();
+      onClose();
+    } catch (err) {
+      toast.error(err);
+      if (n) onAdded();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const toggle = (k: string) =>
+    setPicked((s) => {
+      const next = new Set(s);
+      if (next.has(k)) next.delete(k);
+      else next.add(k);
+      return next;
+    });
+
+  return (
+    <div className="space-y-3">
+      <form
+        className="space-y-1"
+        onSubmit={(e) => {
+          e.preventDefault();
+          if (link.trim()) void read();
+        }}
+      >
+        <label className={label}>
+          {t("plugin.link")}
+          <div className="mt-0.5 flex gap-2">
+            <input
+              className={field}
+              value={link}
+              autoFocus
+              placeholder="https://git.example.com/org/claude-skills.git"
+              onChange={(e) => setLink(e.target.value)}
+            />
+            <button
+              type="submit"
+              className="btn-primary shrink-0 text-sm"
+              disabled={busy || !link.trim()}
+            >
+              {busy && !info ? t("plugin.reading") : t("plugin.read")}
+            </button>
+          </div>
+        </label>
+        <p className={hint}>{t("plugin.linkHint")}</p>
+      </form>
+
+      {error && (
+        <p
+          role="alert"
+          className="rounded border border-status-danger/40 px-2 py-1 text-xs text-status-danger"
+        >
+          {error}
+        </p>
+      )}
+
+      {info && (
+        <div className="space-y-2" data-testid="market-plugins">
+          <div>
+            <p className="text-sm font-medium text-fg-primary">
+              <Package className="mr-1 inline h-4 w-4 text-fg-muted" />
+              {info.name}
+            </p>
+            {info.description && <p className={hint}>{info.description}</p>}
+          </div>
+          {info.plugins.length === 0 ? (
+            <p className={hint}>{t("plugin.none")}</p>
+          ) : (
+            <>
+              <label className="flex items-center gap-2 text-xs text-fg-secondary">
+                <input
+                  type="checkbox"
+                  checked={picked.size === info.plugins.length}
+                  onChange={(e) =>
+                    setPicked(new Set(e.target.checked ? info.plugins.map((p) => p.key) : []))
+                  }
+                />
+                {t("plugin.all")}
+              </label>
+              <ul className="max-h-64 space-y-1 overflow-auto">
+                {info.plugins.map((p) => (
+                  <li key={p.key}>
+                    <label className="flex cursor-pointer items-start gap-2 rounded px-1 py-1 hover:bg-surface-2">
+                      <input
+                        type="checkbox"
+                        className="mt-0.5"
+                        checked={picked.has(p.key)}
+                        onChange={() => toggle(p.key)}
+                      />
+                      <span className="min-w-0 flex-1">
+                        <span className="text-xs font-medium text-fg-primary">{p.name}</span>
+                        <span className="ml-1.5 font-mono text-[10px] text-fg-muted">{p.key}</span>
+                        {p.version && (
+                          <span className="ml-1.5 text-[10px] text-fg-muted">v{p.version}</span>
+                        )}
+                        {have.has(p.key) && (
+                          <span className="ml-1.5 rounded bg-surface-3 px-1 text-[10px] text-fg-secondary">
+                            {t("plugin.have")}
+                          </span>
+                        )}
+                        {p.description && (
+                          <span className="block text-[11px] text-fg-muted">{p.description}</span>
+                        )}
+                      </span>
+                    </label>
+                  </li>
+                ))}
+              </ul>
+              <div className="flex justify-end">
+                <button
+                  type="button"
+                  className="btn-primary text-sm"
+                  disabled={busy || picked.size === 0}
+                  onClick={() => void addPicked()}
+                >
+                  {t("plugin.addPicked", { count: picked.size })}
+                </button>
+              </div>
+            </>
+          )}
+        </div>
+      )}
+
+      <div className="border-t border-border-light pt-2">
+        <button
+          type="button"
+          className="text-xs text-accent hover:underline"
+          aria-expanded={manual}
+          onClick={() => setManual((v) => !v)}
+        >
+          {t("plugin.manual")}
+        </button>
+        {manual && (
+          <form
+            className="mt-2 space-y-2"
+            onSubmit={async (e) => {
+              e.preventDefault();
+              setBusy(true);
+              try {
+                await api.artifacts.addPlugin({
+                  key: key.trim(),
+                  market: market.trim(),
+                  title,
+                  description,
+                });
+                toast.success(t("added"));
+                onAdded();
+                onClose();
+              } catch (err) {
+                toast.error(err);
+              } finally {
+                setBusy(false);
+              }
+            }}
+          >
+            <input
+              className={field}
+              placeholder="my-plugin@my-marketplace"
+              aria-label={t("form.pluginKey")}
+              value={key}
+              onChange={(e) => setKey(e.target.value)}
+            />
+            <input
+              className={field}
+              placeholder="owner/repo · https://… · git@host:org/repo.git"
+              aria-label={t("form.market")}
+              value={market}
+              onChange={(e) => setMarket(e.target.value)}
+            />
+            <input
+              className={field}
+              placeholder={t("form.title")}
+              aria-label={t("form.title")}
+              value={title}
+              onChange={(e) => setTitle(e.target.value)}
+            />
+            <textarea
+              className={field}
+              rows={2}
+              placeholder={t("form.description")}
+              aria-label={t("form.description")}
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+            />
+            <div className="flex justify-end">
+              <button
+                type="submit"
+                className="btn-primary text-sm"
+                disabled={busy || !key.trim() || !market.trim()}
+              >
+                {t("form.save")}
+              </button>
+            </div>
+          </form>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ── File upload ───────────────────────────────────────────────────────────
+
+export function FileUploadPanel({ onAdded }: { onAdded: () => void }) {
+  const { t } = useTranslation("artifacts");
+  const [file, setFile] = useState<File | null>(null);
+  const [title, setTitle] = useState("");
+  const [busy, setBusy] = useState(false);
+  const tooBig = !!file && file.size > 25 * 1024 * 1024;
+  return (
+    <form
+      className="space-y-2"
+      onSubmit={async (e) => {
+        e.preventDefault();
+        if (!file) return;
+        setBusy(true);
+        try {
+          await api.artifacts.uploadFile(file, { title: title.trim() || undefined });
+          toast.success(t("added"));
+          setFile(null);
+          setTitle("");
+          onAdded();
+        } catch (err) {
+          toast.error(err);
+        } finally {
+          setBusy(false);
+        }
+      }}
+    >
+      <label className={label}>
+        {t("file.fromComputer")}
+        <input
+          type="file"
+          data-testid="file-upload"
+          className="mt-0.5 block w-full text-xs text-fg-secondary"
+          onChange={(e) => setFile(e.target.files?.[0] ?? null)}
+        />
+      </label>
+      {tooBig && <p className="text-xs text-status-danger">{t("file.tooBig")}</p>}
+      <div className="flex gap-2">
+        <input
+          className={field}
+          placeholder={t("form.title")}
+          aria-label={t("form.title")}
+          value={title}
+          onChange={(e) => setTitle(e.target.value)}
+        />
+        <button
+          type="submit"
+          className="btn-primary shrink-0 text-sm"
+          disabled={busy || !file || tooBig}
+        >
+          <Upload className="h-3.5 w-3.5" /> {t("file.upload")}
+        </button>
+      </div>
+    </form>
+  );
+}

client/src/components/conversation/ConversationView.tsx

@@ -5,7 +5,19 @@
  * 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. A
+ * chat passes in whether the CLI waits on the user (`waiting`, with
+ * `onOpenTerminal`) and hears how full the context is (`onContext`) and
+ * whether its session has started (`onNotStarted`: no row yet — the CLI may
+ * be asking in the terminal, e.g. to trust the folder, which this then says).
+ * A caller that knows the session has ended passes `ended`: nothing more is
+ * being written, so the catch-up poll drops from 3 s to 60 s and the
+ * sub-agent list stops being rescanned — a `new_event` frame, a reconnect or
+ * the view being shown again still fetch the tail at once.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 /* =============================================================================
@@ -53,13 +65,15 @@
  *
  * ----------------------------------------------------------------------------- */
 
-import { useEffect, useState, useCallback, useRef } from "react";
+import { memo, useEffect, useState, useCallback, useMemo, useRef } from "react";
 import { Loader2, ArrowDown, MessagesSquare, RefreshCw } from "lucide-react";
 import { api } from "../../lib/api";
 import { eventBus } from "../../lib/eventBus";
 import { isRemoteDataRefreshMessage } from "../../lib/remoteDataEvents";
-import { MessageList } from "./MessageList";
+import { MessageList, promptTokens } from "./MessageList";
 import { useSpin } from "../../hooks/useSpin";
+import { useOnScreen, isShown } from "../../hooks/useOnScreen";
+import { throttle } from "../../lib/throttle";
 import { useTranslation } from "react-i18next";
 import type { TranscriptMessage, TranscriptInfo, WSMessage } from "../../lib/types";
 
@@ -69,9 +83,16 @@ import type { TranscriptMessage, TranscriptInfo, WSMessage } from "../../lib/typ
 // hook event. A short visibility-gated poll closes that gap and also rescues
 // the conversation from missed/late WebSocket frames.
 const POLL_INTERVAL_MS = 3000;
+// An ended session writes nothing more: a slow safety poll only, in case it was
+// resumed somewhere whose frames this view missed.
+const ENDED_POLL_INTERVAL_MS = 60000;
 // Rescan the transcripts list periodically so new subagents that spawn
 // mid-session appear in the dropdown without a page reload.
 const TRANSCRIPTS_REFRESH_MS = 15000;
+// A hook burst (Pre + Post per tool call, several sessions) refetches the tail
+// at most this often: the first event still fetches at once, the last is never
+// lost, and a long transcript is not re-read for every single frame.
+const EVENT_FETCH_MS = 1500;
 
 interface ConversationViewProps {
   sessionId: string;
@@ -79,15 +100,56 @@ interface ConversationViewProps {
   /** 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;
+  /** The CLI is asking the user something (a permission prompt). */
+  waiting?: boolean;
+  /** Shows the pane's terminal, where that question is answered. */
+  onOpenTerminal?: () => void;
+  /** Bumped by the chat's Stop: the live line ends with the turn on screen. */
+  stopped?: number;
+  /** The newest reply's prompt size (input + cache) and model: how full the
+   *  context is. */
+  onContext?: (tokens: number, model: string | null) => void;
+  /** A live pane's session has no row yet: the CLI has not started it. */
+  onNotStarted?: (notStarted: boolean) => void;
+  /** The session has ended (and no pane holds it): poll slowly, if at all. */
+  ended?: boolean;
 }
 
-export function ConversationView({
+function ConversationViewPane({
   sessionId,
   initialTranscriptId,
   fill = false,
+  onOpenFile,
+  live = false,
+  follow = 0,
+  waiting = false,
+  onOpenTerminal,
+  stopped = 0,
+  onContext,
+  onNotStarted,
+  ended = false,
 }: ConversationViewProps) {
   const { t } = useTranslation("sessions");
   const [messages, setMessages] = useState<TranscriptMessage[]>([]);
+  // A live pane's session has no row until its first hook — and Claude Code
+  // runs no hook before the folder is trusted, so a trust prompt (or any
+  // other question before the session starts) waits unseen in the terminal.
+  const [notStarted, setNotStarted] = useState(false);
+  useEffect(() => onNotStarted?.(notStarted), [notStarted, onNotStarted]);
+  useEffect(() => {
+    if (!onContext) return;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const m = messages[i]!;
+      if (m.type === "assistant" && m.usage)
+        return onContext(promptTokens(m.usage), m.model ?? null);
+    }
+  }, [messages, onContext]);
   const [total, setTotal] = useState(0);
   const [loading, setLoading] = useState(true);
   const [loadingHistory, setLoadingHistory] = useState(false);
@@ -105,6 +167,7 @@ export function ConversationView({
   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,
@@ -114,6 +177,10 @@ export function ConversationView({
   // Bumped whenever the session or the selected transcript changes: a tail
   // fetch started for the previous transcript must not append to the new one.
   const genRef = useRef(0);
+  // A pane of another workspace or tab stays mounted but hidden: it neither
+  // polls nor follows events, and catches up once when it is shown again.
+  const onShowRef = useRef<() => void>(() => {});
+  const onScreen = useOnScreen(scrollContainerRef, () => onShowRef.current());
   // Refresh-button spinner state - separate from initial `loading` so the
   // existing skeleton doesn't blink during a manual refresh.
 
@@ -131,14 +198,18 @@ export function ConversationView({
       }
     }
     loadTranscripts();
-    const interval = window.setInterval(() => {
-      if (document.visibilityState === "visible") loadTranscripts();
-    }, TRANSCRIPTS_REFRESH_MS);
+    // An ended session spawns no new sub-agents: the load above (re-run when
+    // it ends, for the last ones) is enough.
+    const interval = ended
+      ? undefined
+      : window.setInterval(() => {
+          if (isShown(onScreen)) loadTranscripts();
+        }, TRANSCRIPTS_REFRESH_MS);
     return () => {
       cancelled = true;
       window.clearInterval(interval);
     };
-  }, [sessionId]);
+  }, [sessionId, ended]);
 
   // Sync external initialTranscriptId to internal state
   useEffect(() => {
@@ -164,6 +235,7 @@ export function ConversationView({
           limit: 50,
         });
         if (cancelled) return;
+        setNotStarted(false);
         setMessages(result.messages);
         setTotal(result.total);
         setHasMore(result.has_more);
@@ -171,7 +243,11 @@ export function ConversationView({
         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"));
+        setNotStarted(notYet);
         setMessages([]);
         setTotal(0);
       } finally {
@@ -211,6 +287,7 @@ export function ConversationView({
         limit: 50,
       });
       if (gen !== genRef.current) return; // another transcript is shown now
+      setNotStarted(false);
       if (result.messages.length === 0) return;
 
       lastLineRef.current = result.last_line;
@@ -246,24 +323,33 @@ export function ConversationView({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [sessionId, selectedTranscript]);
 
-  // WebSocket subscription: refetch on every new_event for this session.
+  // WebSocket subscription: refetch on new_event for this session, throttled.
   // Hook coverage isn't complete (a user-typed message fires no hook), so we
   // also poll below to catch what WS misses.
+  const fetchSoon = useMemo(
+    () => throttle(() => void fetchNewMessages(), EVENT_FETCH_MS),
+    [fetchNewMessages]
+  );
+  useEffect(() => () => fetchSoon.cancel(), [fetchSoon]);
   useEffect(() => {
     const unsubscribe = eventBus.subscribe((msg: WSMessage) => {
-      // Hidden tab: the visibility handler below catches up once on show.
-      if (document.visibilityState !== "visible") return;
+      // Hidden tab or hidden pane: catching up once on show is enough.
+      if (!isShown(onScreen)) return;
       if (isRemoteDataRefreshMessage(msg)) {
-        fetchNewMessages();
+        fetchSoon();
         return;
       }
       if (msg.type !== "new_event") return;
       const data = msg.data as { session_id?: string };
       if (data.session_id !== sessionId) return;
-      fetchNewMessages();
+      fetchSoon();
     });
     return unsubscribe;
-  }, [sessionId, fetchNewMessages]);
+  }, [sessionId, fetchSoon, onScreen]);
+
+  onShowRef.current = () => {
+    if (document.visibilityState === "visible") void fetchNewMessages();
+  };
 
   // Resync on WebSocket reconnect: events that landed during a transient
   // disconnect are gone from the bus, but the JSONL still has them, so a
@@ -283,9 +369,12 @@ export function ConversationView({
     let interval: number | null = null;
     function start() {
       if (interval !== null) return;
-      interval = window.setInterval(() => {
-        if (document.visibilityState === "visible") fetchNewMessages();
-      }, POLL_INTERVAL_MS);
+      interval = window.setInterval(
+        () => {
+          if (isShown(onScreen)) fetchNewMessages();
+        },
+        ended ? ENDED_POLL_INTERVAL_MS : POLL_INTERVAL_MS
+      );
     }
     function stop() {
       if (interval !== null) {
@@ -310,7 +399,7 @@ export function ConversationView({
       stop();
       document.removeEventListener("visibilitychange", onVisibility);
     };
-  }, [fetchNewMessages]);
+  }, [fetchNewMessages, onScreen, ended]);
 
   // Manual refresh - surfaces a control in the toolbar so users can force
   // a sync without reloading the page.
@@ -392,6 +481,30 @@ export function ConversationView({
     }
   }, [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) {
@@ -450,38 +563,68 @@ export function ConversationView({
       <div
         ref={scrollContainerRef}
         onScroll={handleScroll}
-        className="flex-1 overflow-y-auto"
+        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>
-        )}
+        {/* A chat keeps its first turn clear of the pane's top-right controls
+            (the outline's file button floats there). */}
+        <div ref={contentRef} className={fill ? "pt-6" : undefined}>
+          {/* 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 && notStarted ? (
+            <div className="mx-auto max-w-md py-12 text-center">
+              <p className="text-sm text-fg-secondary">{t("conversation.notStarted")}</p>
+              <p className="mt-2 text-xs leading-relaxed text-fg-muted">
+                {t("conversation.notStartedBody")}
+              </p>
+              {onOpenTerminal && (
+                <button
+                  type="button"
+                  onClick={onOpenTerminal}
+                  className="btn-secondary mt-3 text-xs"
+                >
+                  {t("conversation.openTerminal")}
+                </button>
+              )}
+            </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}
+              waiting={waiting}
+              onOpenTerminal={onOpenTerminal}
+              stopped={stopped}
+            />
+          )}
+        </div>
       </div>
 
       {/* Claude Desktop's round "back to the end" button */}
@@ -520,3 +663,7 @@ export function ConversationView({
     </div>
   );
 }
+
+/** Memoized: a chat's prompt box lives in its parent (PaneChat), and every
+ *  keystroke there re-rendered the whole conversation. */
+export const ConversationView = memo(ConversationViewPane);

client/src/components/conversation/MarkdownContent.tsx

@@ -4,7 +4,14 @@
  * 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. A file path — absolute, or relative with a folder and
+ * an extension (`server/lib/x.js`), with or without a `:line` suffix, bare, in
+ * inline code or as a markdown link's target — opens through `OpenFileContext`
+ * when the page provides one (the page resolves a relative one against its own
+ * folder); `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
@@ -77,7 +84,12 @@ const HR_RE = /^\s*(-{3,}|\*{3,}|_{3,})\s*$/;
 const UL_RE = /^(\s*)([-*+])\s+(.*)$/;
 const OL_RE = /^(\s*)(\d+)\.\s+(.*)$/;
 const QUOTE_RE = /^\s*>\s?(.*)$/;
-const TABLE_DIVIDER_RE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$/;
+const TABLE_DIVIDER_RE = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$/;
+
+/** A GFM table starts at a line holding a pipe that is followed by a divider. */
+function isTableStart(lines: string[], i: number): boolean {
+  return lines[i]!.includes("|") && i + 1 < lines.length && TABLE_DIVIDER_RE.test(lines[i + 1]!);
+}
 
 function splitTableRow(line: string): string[] {
   // Trim leading/trailing pipes, then split, respecting escaped pipes.
@@ -164,7 +176,7 @@ function parseBlocks(src: string): Block[] {
     }
 
     // Table: header line followed by an alignment divider
-    if (line.includes("|") && i + 1 < lines.length && TABLE_DIVIDER_RE.test(lines[i + 1]!)) {
+    if (isTableStart(lines, i)) {
       const header = splitTableRow(line);
       const aligns = parseAlignments(lines[i + 1]!);
       i += 2;
@@ -220,7 +232,8 @@ function parseBlocks(src: string): Block[] {
       continue;
     }
 
-    // Paragraph: collect until a blank line or the start of another block
+    // Paragraph: collect until a blank line or the start of another block —
+    // a table included, which (as in GFM) may follow prose with no blank line.
     const paraLines: string[] = [line];
     i++;
     while (i < lines.length) {
@@ -232,7 +245,8 @@ function parseBlocks(src: string): Block[] {
         HR_RE.test(nl) ||
         UL_RE.test(nl) ||
         OL_RE.test(nl) ||
-        QUOTE_RE.test(nl)
+        QUOTE_RE.test(nl) ||
+        isTableStart(lines, i)
       ) {
         break;
       }
@@ -244,6 +258,113 @@ 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.
+// A `:12` or `:12:5` line suffix belongs to the link (Claude writes `path:line`).
+const PATH_RE = /^(?:\/[^\s/<>()'"`,;:]*[^\s/<>()'"`,;:.!?]){2,}(?::\d+(?::\d+)?)?/;
+// A relative path needs a folder AND an extension starting with a letter
+// (`docs/API.md`, `./a/b.ts:9`), so "and/or" and "3/4.5" stay text; a first segment with an inner dot is a host
+// (`github.com/x.js`), not a folder — a leading one (`.claude/…`) is a folder.
+const REL_PATH_RE =
+  /^(?:\.{1,2}\/)*(?:\.?[\w@-][\w@-]*\/)(?:[\w.@-]+\/)*[\w.@-]*[\w@-]\.[A-Za-z][A-Za-z0-9]{0,9}(?::\d+(?::\d+)?)?(?![\p{L}\p{N}_/])/u;
+/** A path at the start of `text`, absolute or relative, or null. */
+const matchPath = (text: string) => PATH_RE.exec(text)?.[0] ?? REL_PATH_RE.exec(text)?.[0] ?? null;
+/** `a/b.ts:12:5` → `a/b.ts`: what is opened. */
+export const stripLine = (p: string) => p.replace(/(?::\d+){1,2}$/, "");
+// A markdown link target that is a page, not a file.
+const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+// 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 markdown link's file target as a path: `%20` decoded, `#L12` → `:12`. */
+function decodeHref(href: string): string {
+  let p = href
+    .replace(/^file:\/\//i, "")
+    .replace(/#L(\d+)(?:-L?\d+)?$/, ":$1")
+    .replace(/#.*$/, "");
+  try {
+    p = decodeURIComponent(p);
+  } catch {
+    /* a stray % stays as written */
+  }
+  return p;
+}
+
+/** 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(stripLine(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) && matchPath(rest);
+    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 +388,12 @@ 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(matchPath(codeM[1]!) === codeM[1] ? <PathLink path={codeM[1]!}>{code}</PathLink> : code);
       i += codeM[0].length;
       continue;
     }
@@ -280,7 +402,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>
       );
@@ -315,9 +437,21 @@ function renderInline(text: string, baseKey = ""): React.ReactNode[] {
     // Markdown link
     const linkM = rest.match(/^\[([^\]]+)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/);
     if (linkM) {
+      const href = linkM[2]!;
+      // `[x.ts](src/x.ts#L12)` names a file: open it like a bare path.
+      if (
+        /^file:\/\//i.test(href) ||
+        (!SCHEME_RE.test(href) && !href.startsWith("#") && !href.startsWith("//"))
+      ) {
+        push(
+          <PathLink path={decodeHref(href)}>{renderInline(linkM[1]!, `${baseKey}-l${n}`)}</PathLink>
+        );
+        i += linkM[0].length;
+        continue;
+      }
       push(
         <a
-          href={linkM[2]!}
+          href={href}
           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"
@@ -330,22 +464,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) ? matchPath(rest) : null;
+    if (pathM) {
+      push(<PathLink path={pathM}>{pathM}</PathLink>);
+      i += pathM.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++;
   }

client/src/components/conversation/MessageList.tsx

@@ -4,7 +4,29 @@
  * 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`) — any other attached file as a
+ * chip that opens its preview through `onOpenFile` —, 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. An
+ * AskUserQuestion is its own card (`AskCard`), not part of the collapsed work
+ * line: each question with the answer the user picked or typed. 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 calls still running (several when it runs them in parallel),
+ * else "Thinking…", or the question the CLI waits on with a way to its
+ * terminal (`waiting`) — and, like the terminal's status line, how long the
+ * turn has run and the output tokens it has made; a call running long shows
+ * its own time, and a line silent for minutes turns amber. A turn that ended
+ * closes with how long it took and its output.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 /* =============================================================================
@@ -53,7 +75,8 @@
  *
  * ----------------------------------------------------------------------------- */
 
-import { memo, useState, useMemo } from "react";
+import { Fragment, memo, useContext, useEffect, useRef, useState, useMemo } from "react";
+import { ImageLightbox } from "../ImageLightbox";
 import { useTranslation } from "react-i18next";
 import i18n from "../../i18n";
 import {
@@ -69,6 +92,13 @@ import {
   Pencil,
   Workflow,
   Cog,
+  FileText,
+  Loader2,
+  Check,
+  Hand,
+  SquareTerminal,
+  MessageCircleQuestion,
+  CornerDownRight,
 } from "lucide-react";
 import type { TranscriptMessage, TranscriptContent, TranscriptSender } from "../../lib/types";
 
@@ -112,13 +142,27 @@ const SENDER_STYLES: Record<
   },
 };
 import { ToolCallBlock, buildSummary, renderInput, renderResult } from "./ToolCallBlock";
-import { MarkdownContent } from "./MarkdownContent";
-import { fmt, formatModelName } from "../../lib/format";
+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;
+  /** The CLI is asking the user something (a permission prompt): the live
+   *  line says so instead of "Thinking…". */
+  waiting?: boolean;
+  /** Shows the pane's terminal, where that question is answered. */
+  onOpenTerminal?: () => void;
+  /** Bumped by the chat's Stop: the turn on screen is over, even when the
+   *  transcript never says so. */
+  stopped?: number;
 }
 
 /** Build a map from tool_use id → tool_result for matching */
@@ -135,6 +179,27 @@ function buildToolResultMap(messages: TranscriptMessage[]): Map<string, Transcri
   return map;
 }
 
+type ResultMap = ReturnType<typeof buildToolResultMap>;
+
+/** The map is rebuilt on every tail append, but a block's own result keeps its
+ *  identity (old messages are kept, not copied): comparing just those lets a
+ *  memoized row skip the re-render when nothing it shows changed. */
+const sameResults = (blocks: TranscriptContent[], a: ResultMap, b: ResultMap) =>
+  a === b || blocks.every((bl) => !bl.id || a.get(bl.id) === b.get(bl.id));
+
+const sameBlocks = (a: TranscriptContent[], b: TranscriptContent[]) =>
+  a === b || (a.length === b.length && a.every((bl, i) => bl === b[i]));
+
+/** 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. */
+export 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 +239,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>
   );
 }
@@ -390,35 +475,189 @@ type Item =
   | { 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: "work"; key: string; blocks: TranscriptContent[] }
+  | { kind: "ask"; key: string; block: TranscriptContent }
+  | { kind: "edits"; key: string; blocks: TranscriptContent[] }
+  | { kind: "done"; key: string; ms: number; output: number };
+
+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[] = [];
+  // The turn's prompt time, its newest assistant line and its output so far,
+  // for the "Done in …" line under a turn that ended.
+  let start: string | null = null;
+  let reply: TranscriptMessage | null = null;
+  let output = outputCounter();
+  const endTurn = (key: string) => {
+    if (edits.length) items.push({ kind: "edits", key: `edits:${key}`, blocks: edits });
+    edits = [];
+    if (start && reply?.timestamp && reply.stop_reason === "end_turn") {
+      const ms = parseDate(reply.timestamp).getTime() - parseDate(start).getTime();
+      items.push({ kind: "done", key: `done:${key}`, ms, output: output.total });
+    }
+    reply = null;
+    output = outputCounter();
+  };
   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") return items.push({ kind: "user", key, msg });
-    if (sender !== "assistant") return items.push({ kind: "row", key, msg });
+    if (sender === "user") {
+      endTurn(key);
+      start = msg.timestamp ?? null;
+      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 });
+    }
+    reply = msg;
+    if (msg.usage) output.add(msg.usage);
     msg.content.forEach((block, b) => {
       const last = items[items.length - 1];
-      if (block.type === "tool_use" || (block.type === "thinking" && block.text)) {
+      if (block.type === "tool_use" && EDIT_TOOLS.has(block.name ?? "")) edits.push(block);
+      // A question to the user is a turn of the conversation, not hidden work.
+      if (block.type === "tool_use" && block.name === "AskUserQuestion") {
+        items.push({ kind: "ask", key: `${key}:${b}`, block });
+      } else 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.text?.trim()) {
+      } 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;
 }
 
-export function MessageList({ messages, loading }: MessageListProps) {
+/** 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 EditedFilesCard({
+  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>
+  );
+}
+const EditedFiles = memo(
+  EditedFilesCard,
+  (p, n) =>
+    p.onOpenFile === n.onOpenFile &&
+    sameBlocks(p.blocks, n.blocks) &&
+    sameResults(n.blocks, p.toolResultMap, n.toolResultMap)
+);
+
+function MessageListView({
+  messages,
+  loading,
+  onOpenFile,
+  live = false,
+  waiting = false,
+  onOpenTerminal,
+  stopped = 0,
+}: MessageListProps) {
   const { t } = useTranslation("sessions");
   const toolResultMap = useMemo(() => buildToolResultMap(messages), [messages]);
   const keys = useMemo(() => messageKeys(messages), [messages]);
+  const lastKey = keys[keys.length - 1] ?? null;
+  // The newest line when Stop was pressed. Esc before the model wrote anything
+  // puts the prompt back in Claude Code's input box and writes no
+  // "[Request interrupted…]" line (issue #74), so the transcript still ends on
+  // the prompt: no live line until a newer one arrives.
+  const [stop, setStop] = useState<{ n: number; on: string | null }>({ n: stopped, on: null });
+  if (stop.n !== stopped) setStop({ n: stopped, on: lastKey });
+  const halted = stop.on !== null && stop.on === lastKey;
+  const pending = useMemo(
+    () => (live && !halted ? workingOn(messages, toolResultMap) : null),
+    [live, halted, messages, toolResultMap]
+  );
+  const stats = useMemo(() => (pending ? turnStats(messages) : null), [pending, messages]);
   const items = useMemo(() => chatItems(messages, keys), [messages, keys]);
 
   if (loading) {
@@ -434,33 +673,478 @@ export function MessageList({ messages, loading }: MessageListProps) {
   }
 
   return (
-    <div className="mx-auto w-full max-w-3xl 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} />;
+    <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 "ask":
+              return (
+                <AskCard
+                  key={item.key}
+                  block={item.block}
+                  result={item.block.id ? (toolResultMap.get(item.block.id) ?? null) : null}
+                />
+              );
+            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}
+                />
+              );
+            case "done":
+              return <TurnDone key={item.key} ms={item.ms} output={item.output} />;
+          }
+        })}
+        {pending && (
+          <RunningStep
+            {...pending}
+            start={stats?.start ?? null}
+            tokens={stats?.output ?? 0}
+            waiting={waiting}
+            onOpenTerminal={onOpenTerminal}
+          />
+        )}
+      </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 calls of the turn
+ *  still waiting for their results (`blocks`, oldest first — parallel calls
+ *  finish in any order), `since` the oldest one's time, `last` the newest
+ *  line's; `blocks` is empty while it thinks. Null once the turn ended. */
+export function workingOn(
+  messages: TranscriptMessage[],
+  results: Map<string, TranscriptContent>,
+  now = Date.now()
+): { blocks: TranscriptContent[]; since: string | null; last: string | null } | null {
+  const blocks: TranscriptContent[] = [];
+  let since: string | null = null;
+  let last: string | null = null;
+  // The newest line's verdict: undefined until it is found.
+  let alive: boolean | undefined;
+  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 at = msg.timestamp ?? null;
+    const fresh = !at || now - parseDate(at).getTime() < IDLE_AFTER_MS;
+    const newest = alive === undefined;
+    if (newest) last = at;
+    if (msg.type === "assistant") {
+      // "end_turn": over, whatever the transcript failed to pair.
+      if (newest && msg.stop_reason === "end_turn") return null;
+      for (const b of [...msg.content].reverse()) {
+        if (b.type === "tool_use" && b.id && !results.has(b.id)) {
+          blocks.unshift(b);
+          since = at;
         }
+      }
+      // "tool_use": a call follows. None (an older server): over.
+      if (newest) alive = msg.stop_reason === "tool_use" && fresh;
+      continue;
+    }
+    // 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;
+    if (newest) alive = fresh;
+    // The prompt that opened the turn: nothing before it is this turn's.
+    if (text) break;
+  }
+  if (blocks.length) return { blocks, since, last };
+  return alive ? { blocks, since: null, last } : null;
+}
+
+/** Output tokens counted once per API call: Claude Code writes one line per
+ *  content block, each repeating its call's usage — consecutive lines with
+ *  the same prompt size are one call. */
+function outputCounter() {
+  let total = 0;
+  let call: string | null = null;
+  let callOutput = 0;
+  return {
+    add(u: NonNullable<TranscriptMessage["usage"]>) {
+      const key = `${u.input_tokens}:${u.cache_read_input_tokens ?? 0}:${u.cache_creation_input_tokens ?? 0}`;
+      if (key !== call) {
+        total += callOutput;
+        call = key;
+        callOutput = 0;
+      }
+      callOutput = Math.max(callOutput, u.output_tokens || 0);
+    },
+    get total() {
+      return total + callOutput;
+    },
+  };
+}
+
+/** The live turn so far, as the terminal counts it: `start` is the prompt
+ *  that opened it, `output` the output tokens of every API call since. */
+export function turnStats(messages: TranscriptMessage[]): { start: string | null; output: number } {
+  const output = outputCounter();
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]!;
+    if (msg.type === "assistant") {
+      if (msg.usage) output.add(msg.usage);
+      continue;
+    }
+    const sender = msg.sender ?? "user";
+    if (sender === "user" && msg.content.some((c) => c.type === "text")) {
+      return { start: msg.timestamp ?? null, output: output.total };
+    }
+  }
+  return { start: null, output: output.total };
+}
+
+// A call running this long shows its own time beside the turn's.
+const STEP_SHOWN_MS = 30_000;
+// No new line for this long: the line turns amber — the step may be stuck.
+const QUIET_MS = 3 * 60_000;
+
+/** A number that counts up to its new value instead of jumping (none when
+ *  the user asked for reduced motion). */
+function useCountUp(value: number): number {
+  const [shown, setShown] = useState(value);
+  const shownRef = useRef(value);
+  useEffect(() => {
+    const from = shownRef.current;
+    if (from === value) return;
+    const reduce = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+    if (reduce || typeof requestAnimationFrame === "undefined") {
+      shownRef.current = value;
+      setShown(value);
+      return;
+    }
+    const t0 = performance.now();
+    let raf = 0;
+    const step = (t: number) => {
+      const k = Math.min(1, (t - t0) / 600);
+      shownRef.current = Math.round(from + (value - from) * k);
+      setShown(shownRef.current);
+      if (k < 1) raf = requestAnimationFrame(step);
+    };
+    raf = requestAnimationFrame(step);
+    return () => cancelAnimationFrame(raf);
+  }, [value]);
+  return shown;
+}
+
+/** A call's one-line title: its description (Claude Code's Bash
+ *  `description`), else the tool and its target. */
+function stepTitle(block: TranscriptContent): string {
+  const input = block.input as Record<string, unknown> | undefined;
+  return typeof input?.description === "string" && input.description
+    ? input.description
+    : [block.name, buildSummary(block)].filter(Boolean).join(" ");
+}
+
+/** The terminal's live line: the step running now (or the question the CLI
+ *  waits on), then the turn's time and output tokens so far. */
+function RunningStep({
+  blocks,
+  since,
+  last,
+  start,
+  tokens,
+  waiting,
+  onOpenTerminal,
+}: {
+  blocks: TranscriptContent[];
+  since: string | null;
+  last: string | null;
+  start: string | null;
+  tokens: number;
+  waiting: boolean;
+  onOpenTerminal?: () => void;
+}) {
+  const { t } = useTranslation("sessions");
+  const [now, setNow] = useState(() => Date.now());
+  const [showAll, setShowAll] = useState(false);
+  const boxRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    // A hidden tab or a hidden pane (another workspace, kept mounted) shows
+    // no clock: skip the re-render until it is on screen again.
+    const timer = window.setInterval(() => {
+      const el = boxRef.current;
+      if (document.visibilityState !== "visible" || (el && el.getClientRects().length === 0))
+        return;
+      setNow(Date.now());
+    }, 1000);
+    return () => window.clearInterval(timer);
+  }, []);
+  const counted = useCountUp(tokens);
+  const age = (at: string | null) => (at ? now - parseDate(at).getTime() : 0);
+  const first = blocks[0];
+  const step = first ? age(since) : 0;
+  const quiet = !waiting && age(last) > QUIET_MS;
+  const title = waiting
+    ? first
+      ? t("conversation.waitingFor", { step: stepTitle(first) })
+      : t("conversation.waiting")
+    : first
+      ? stepTitle(first)
+      : t("conversation.working");
+  const extra = [
+    start && formatMs(age(start)),
+    tokens > 0 && t("conversation.turnTokens", { tokens: fmt(counted) }),
+    quiet && !first && t("conversation.quiet", { time: formatMs(age(last)) }),
+  ].filter(Boolean);
+  const amber = waiting || quiet;
+  return (
+    <div ref={boxRef} data-testid="chat-running-step" className="space-y-1 text-sm text-fg-muted">
+      <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
+        {waiting ? (
+          <Hand className="h-3.5 w-3.5 flex-shrink-0 text-status-warning" />
+        ) : (
+          <Loader2
+            className={`h-3.5 w-3.5 flex-shrink-0 animate-spin ${quiet ? "text-status-warning" : "text-accent"}`}
+          />
+        )}
+        <span className={`min-w-0 truncate ${amber ? "text-status-warning" : "text-shimmer"}`}>
+          {title}
+        </span>
+        {blocks.length > 1 && (
+          <button
+            type="button"
+            onClick={() => setShowAll((v) => !v)}
+            aria-expanded={showAll}
+            className="flex-shrink-0 rounded-full border border-border px-1.5 text-xs hover:bg-surface-2"
+          >
+            {t("conversation.moreSteps", { count: blocks.length - 1 })}
+          </button>
+        )}
+        {step > STEP_SHOWN_MS && (
+          <span
+            className={`flex-shrink-0 font-mono text-xs ${step > QUIET_MS ? "text-status-warning" : ""}`}
+          >
+            {formatMs(step)}
+          </span>
+        )}
+        {extra.length > 0 && (
+          <span className="flex-shrink-0 font-mono text-xs">{`(${extra.join(" · ")})`}</span>
+        )}
+        {waiting && onOpenTerminal && (
+          <button
+            type="button"
+            data-testid="chat-open-terminal"
+            onClick={onOpenTerminal}
+            className="flex flex-shrink-0 items-center gap-1 rounded-md border border-status-warning/40 px-2 py-0.5 text-xs text-status-warning hover:bg-status-warning/10"
+          >
+            <SquareTerminal className="h-3.5 w-3.5" />
+            {t("conversation.openTerminal")}
+          </button>
+        )}
+      </div>
+      {showAll && blocks.length > 1 && (
+        <ul className="ml-5 space-y-0.5 text-xs">
+          {blocks.map((b, i) => (
+            <li key={b.id ?? i} className="truncate">
+              {stepTitle(b)}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+/** Under a turn that ended: how long it took and the output it made. */
+/** An option's label carries the model's " (Recommended)" marker into the
+ *  answer the CLI records; the user's pick reads without it (every picked
+ *  label of a multi-select answer too). */
+function stripRecommended(answer: string | undefined): string | undefined {
+  return answer?.replace(/\s*\(recommended\)/gi, "").trim();
+}
+
+/** An AskUserQuestion: each question with the answer the user picked or
+ *  typed (the result's `answers`, minus the " (Recommended)" marker),
+ *  "declined" when they refused it, no answer yet while the CLI still asks. */
+function AskCard({
+  block,
+  result,
+}: {
+  block: TranscriptContent;
+  result: TranscriptContent | null;
+}) {
+  const { t } = useTranslation("sessions");
+  const input = block.input as { questions?: unknown } | undefined;
+  const questions = (Array.isArray(input?.questions) ? input.questions : [])
+    .map((q) => (q && typeof q === "object" ? (q as { question?: unknown }).question : null))
+    .filter((q): q is string => typeof q === "string");
+  return (
+    <div
+      data-testid="chat-ask"
+      className="space-y-2 rounded-xl border border-border px-3 py-2 text-sm"
+    >
+      {questions.map((q, i) => {
+        const answer = stripRecommended(result?.answers?.[q]);
+        return (
+          <div key={i}>
+            <div className="flex items-start gap-1.5 text-fg-secondary">
+              <MessageCircleQuestion className="mt-0.5 h-3.5 w-3.5 flex-shrink-0" />
+              <span>{q}</span>
+            </div>
+            {answer && (
+              <div className="ml-5 mt-0.5 flex items-start gap-1.5 font-medium text-fg-primary">
+                <CornerDownRight className="mt-0.5 h-3.5 w-3.5 flex-shrink-0 text-fg-muted" />
+                <span className="whitespace-pre-wrap">{answer}</span>
+              </div>
+            )}
+          </div>
+        );
       })}
+      {result?.is_error && (
+        <div className="text-xs text-fg-muted">{t("conversation.askDeclined")}</div>
+      )}
+    </div>
+  );
+}
+
+function TurnDone({ ms, output }: { ms: number; output: number }) {
+  const { t } = useTranslation("sessions");
+  return (
+    <div data-testid="chat-turn-done" className="flex items-center gap-1.5 text-xs text-fg-muted">
+      <Check className="h-3 w-3 flex-shrink-0" />
+      {[
+        t("conversation.turnDone", { time: formatMs(ms) }),
+        output > 0 && t("conversation.turnTokens", { tokens: fmt(output) }),
+      ]
+        .filter(Boolean)
+        .join(" · ")}
     </div>
   );
 }
 
 const meta = "text-[10px] font-mono text-fg-muted";
 
+// What the prompt box sends for an attached file: its saved path under the
+// drop dir (`<data dir>/drops/<16 hex>[-name].ext`, server/routes/run.js; the
+// older `<tmp>/agenthub-drops-<uid>/` still in past transcripts).
+const DROP_PATH =
+  /(?<=^|\s)(\S*[\\/](?:agenthub-drops--?\d+|drops)[\\/]([0-9a-f]{16}(?:-[A-Za-z0-9._-]+)?\.[A-Za-z0-9]+))(?=\s|$)/gi;
+const IMAGE_EXT = /\.(?:png|jpe?g|gif|webp)$/i;
+// 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-file paths (and Claude Code's
+ *  `[Image #N]` placeholders for them), the images' names and the other
+ *  files' full paths. */
+export function splitDropImages(text: string): {
+  text: string;
+  images: string[];
+  files: string[];
+} {
+  const images: string[] = [];
+  const files: string[] = [];
+  const rest = text.replace(DROP_PATH, (_all, full: string, name: string) => {
+    if (IMAGE_EXT.test(name)) images.push(name);
+    else files.push(full);
+    return "";
+  });
+  return {
+    text:
+      images.length || files.length
+        ? rest
+            .replace(/\[Image #\d+\]/g, "")
+            .replace(/[ \t]+$/gm, "")
+            .trim()
+        : text,
+    images,
+    files,
+  };
+}
+
+/** 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;
+}
+
+/** A dropped file other than an image: a chip that opens its preview when the
+ *  page can (`OpenFileContext`). */
+function DropFile({ path }: { path: string }) {
+  const open = useContext(OpenFileContext);
+  const name = path
+    .split(/[\\/]/)
+    .pop()!
+    .replace(/^[0-9a-f]{16}-?/i, "");
+  const ext = /\.([A-Za-z0-9]+)$/.exec(name)?.[1]?.toUpperCase();
+  return (
+    <button
+      type="button"
+      disabled={!open}
+      onClick={() => open?.(path)}
+      title={path}
+      className="flex max-w-64 items-center gap-2 rounded-xl border border-border bg-surface-2 px-3 py-2 text-left text-xs enabled:hover:border-accent/50"
+    >
+      <FileText className="h-4 w-4 shrink-0 text-fg-muted" />
+      <span className="truncate text-fg-primary">{name}</span>
+      {ext && <span className="shrink-0 font-mono text-[10px] text-fg-muted">{ext}</span>}
+    </button>
+  );
+}
+
+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;
@@ -468,35 +1152,58 @@ 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 files = blocks.flatMap((b) => b?.files ?? []);
+  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"
     >
-      <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)]"
-            : ""
-        }`}
-      >
-        {msg.content.map((block, b) => {
-          if (block.type !== "text" || !block.text) return null;
-          // Plain typing reads as typed; anything structured keeps its rendering.
-          const plain =
-            !hasTuiTags(block.text) &&
-            !isSkillContent(block.text) &&
-            !isTaskNotification(block.text);
-          return plain ? (
-            <p key={b} className="whitespace-pre-wrap break-words leading-relaxed">
-              {stripAnsi(block.text).trim()}
-            </p>
-          ) : (
-            renderTextBlock(block.text, b)
-          );
-        })}
-      </div>
+      {images.length + files.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} />
+          ))}
+          {files.map((path) => (
+            <DropFile key={path} path={path} />
+          ))}
+        </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"
@@ -540,8 +1247,8 @@ const AssistantText = memo(function AssistantText({
       >
         {msg.model && <span>{formatModelName(msg.model)}</span>}
         {msg.usage && (
-          <span>
-            ↓ {fmt(msg.usage.input_tokens)} · ↑ {fmt(msg.usage.output_tokens)}
+          <span title={usageTitle(msg.usage)}>
+            ↓ {fmt(promptTokens(msg.usage))} · ↑ {fmt(msg.usage.output_tokens)}
           </span>
         )}
         {msg.timestamp && <span>{formatLocalTime(msg.timestamp)}</span>}
@@ -592,6 +1299,8 @@ const WORK_KIND: Record<string, string> = {
 };
 
 /** "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) {
@@ -600,7 +1309,9 @@ export function workLabel(blocks: TranscriptContent[]): string {
     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);
@@ -684,7 +1395,7 @@ function WorkStep({
 
 /** What the assistant did between two replies as one line, opening onto
  *  one framed list of its steps. */
-const WorkGroup = memo(function WorkGroup({
+function WorkGroupLine({
   blocks,
   toolResultMap,
 }: {
@@ -706,11 +1417,16 @@ const WorkGroup = memo(function WorkGroup({
       </Disclosure>
     </div>
   );
-});
+}
+const WorkGroup = memo(
+  WorkGroupLine,
+  (p, n) =>
+    sameBlocks(p.blocks, n.blocks) && sameResults(n.blocks, p.toolResultMap, n.toolResultMap)
+);
 
 /** 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({
+function MessageRowView({
   msg,
   toolResultMap,
 }: {
@@ -751,8 +1467,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>
@@ -826,4 +1545,11 @@ const MessageRow = memo(function MessageRow({
       </div>
     </div>
   );
-});
+}
+const MessageRow = memo(
+  MessageRowView,
+  (p, n) => p.msg === n.msg && sameResults(n.msg.content, p.toolResultMap, n.toolResultMap)
+);
+
+/** Memoized: its owner re-renders on scroll state and its parent's typing. */
+export const MessageList = memo(MessageListView);

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.hidden.test.tsx

@@ -0,0 +1,96 @@
+/**
+ * @file ConversationView.hidden.test.tsx
+ * @description A chat kept mounted in a hidden pane (another workspace or
+ * tab, `display:none`) does not follow the live stream: a new_event for its
+ * session fetches nothing while its box is off screen, and showing it again
+ * catches the tail up once. On screen, a burst of events is throttled to one
+ * fetch at once plus one after the burst.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { act, render, screen } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ConversationView } from "../ConversationView";
+import { api } from "../../../lib/api";
+import { eventBus } from "../../../lib/eventBus";
+
+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 intersect: ((visible: boolean) => void) | null = null;
+const original = globalThis.IntersectionObserver;
+beforeEach(() => {
+  intersect = null;
+  // @ts-expect-error test stub
+  globalThis.IntersectionObserver = class {
+    constructor(cb: (e: { isIntersecting: boolean }[]) => void) {
+      intersect = (visible) => cb([{ isIntersecting: visible }]);
+    }
+    observe() {}
+    disconnect() {}
+  };
+});
+afterEach(() => {
+  globalThis.IntersectionObserver = original;
+  vi.useRealTimers();
+  vi.clearAllMocks();
+});
+
+const event = () =>
+  act(() => eventBus.publish({ type: "new_event", data: { session_id: "s1" } } as never));
+const calls = () => vi.mocked(api.sessions.transcript).mock.calls.length;
+
+describe("ConversationView in a hidden pane", () => {
+  it("fetches nothing while hidden and catches up once when shown", async () => {
+    render(<ConversationView sessionId="s1" fill live />);
+    await screen.findByText("hello");
+    const before = calls();
+
+    act(() => intersect?.(false));
+    event();
+    event();
+    expect(calls()).toBe(before);
+
+    act(() => intersect?.(true));
+    await act(async () => {});
+    expect(calls()).toBe(before + 1);
+  });
+
+  it("throttles a burst of events on screen", async () => {
+    render(<ConversationView sessionId="s1" fill live />);
+    await screen.findByText("hello");
+    vi.useFakeTimers();
+    const before = calls();
+    event();
+    event();
+    event();
+    // The first fetches at once; the rest wait for the throttle window.
+    expect(calls()).toBe(before + 1);
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1600);
+    });
+    expect(calls()).toBe(before + 2);
+  });
+});

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

@@ -0,0 +1,58 @@
+/**
+ * @file ConversationView.notYet.test.tsx
+ * @description A live pane's new session has no row until its first hook:
+ * its 404 shows no "Session not found" (a replay still shows it) but says the
+ * session has not started — the CLI may be asking in the terminal, e.g. to
+ * trust the folder — offers the terminal, and tells the chat (`onNotStarted`).
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { fireEvent, 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();
+  });
+
+  it("says the session has not started and offers the terminal (a trust prompt)", async () => {
+    const onOpenTerminal = vi.fn();
+    const onNotStarted = vi.fn();
+    render(
+      <ConversationView
+        sessionId="new"
+        fill
+        live
+        onOpenTerminal={onOpenTerminal}
+        onNotStarted={onNotStarted}
+      />
+    );
+    expect(await screen.findByText("The session has not started yet.")).toBeTruthy();
+    expect(screen.queryByText("No conversation records found.")).toBeNull();
+    fireEvent.click(screen.getByText("Open terminal"));
+    expect(onOpenTerminal).toHaveBeenCalled();
+    expect(onNotStarted).toHaveBeenLastCalledWith(true);
+  });
+});

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

@@ -7,8 +7,52 @@
  */
 
 import { describe, it, expect } from "vitest";
-import { render, screen } from "@testing-library/react";
-import { MarkdownContent } from "../MarkdownContent";
+import { vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { MarkdownContent, OpenFileContext } from "../MarkdownContent";
+import { resolveIn } from "../../../lib/resolvePath";
+
+function withOpen(text: string) {
+  const open = vi.fn();
+  render(
+    <OpenFileContext.Provider value={open}>
+      <MarkdownContent text={text} />
+    </OpenFileContext.Provider>
+  );
+  return open;
+}
+
+describe("file links", () => {
+  it("opens a relative path with its line suffix stripped", () => {
+    const open = withOpen("See server/lib/x.js:42 for it.");
+    fireEvent.click(screen.getByRole("button", { name: "server/lib/x.js:42" }));
+    expect(open).toHaveBeenCalledWith("server/lib/x.js");
+  });
+
+  it("opens an absolute path with a line suffix and one in inline code", () => {
+    const open = withOpen("At /a/b/c.ts:9 and `docs/API.md`.");
+    fireEvent.click(screen.getByRole("button", { name: "/a/b/c.ts:9" }));
+    fireEvent.click(screen.getByRole("button", { name: "docs/API.md" }));
+    expect(open.mock.calls).toEqual([["/a/b/c.ts"], ["docs/API.md"]]);
+  });
+
+  it("opens a markdown link to a file instead of navigating", () => {
+    const open = withOpen("[the panel](client/src/A%20B.tsx#L12) and [web](https://x.dev)");
+    fireEvent.click(screen.getByRole("button", { name: "the panel" }));
+    expect(open).toHaveBeenCalledWith("client/src/A B.tsx");
+    expect(screen.getByRole("link", { name: "web" })).toHaveAttribute("href", "https://x.dev");
+  });
+
+  it("leaves prose with slashes as text", () => {
+    withOpen("and/or, 3/4.5, github.com/x.js, TCP/IP.");
+    expect(screen.queryAllByRole("button")).toHaveLength(0);
+  });
+
+  it("resolves a relative path against the pane's folder", () => {
+    expect(resolveIn("/w/repo/", "./server/../docs/API.md")).toBe("/w/repo/docs/API.md");
+    expect(resolveIn("/w/repo", "/etc/x.conf")).toBe("/etc/x.conf");
+  });
+});
 
 describe("<MarkdownContent />", () => {
   it("renders fenced code blocks with the language label", () => {
@@ -66,10 +110,61 @@ 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
     expect(container.firstChild).not.toBeNull();
     expect(container.querySelectorAll("p, ul, ol, blockquote, pre, hr").length).toBe(0);
   });
+
+  it("renders a table that follows prose with no blank line (issue #83)", () => {
+    const text = 'Cách kiểm tra:\n| Token xoá | Số chỗ |\n|---|---|\n| `width="N"` | 29 |';
+    const { container } = render(<MarkdownContent text={text} />);
+    expect(container.querySelector("p")?.textContent).toBe("Cách kiểm tra:");
+    expect(container.querySelectorAll("th").length).toBe(2);
+    expect(container.querySelectorAll("tbody tr").length).toBe(1);
+    expect(container.textContent).not.toContain("|---|");
+  });
+
+  it("accepts a GFM divider with single dashes", () => {
+    const { container } = render(<MarkdownContent text={"| a | b |\n|-|:-:|\n| 1 | 2 |"} />);
+    expect(container.querySelectorAll("th").length).toBe(2);
+  });
 });

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

@@ -0,0 +1,104 @@
+/**
+ * @file MessageList.ask.test.tsx
+ * @description An AskUserQuestion call is not folded into the collapsed work
+ * line: the chat shows it as its own card — each question with the answer the
+ * user picked or typed (without the option's " (Recommended)" marker), "declined" when they refused it, nothing yet while the
+ * CLI still waits.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { describe, it, expect } from "vitest";
+import { render, screen, within } from "@testing-library/react";
+import { MessageList } from "../MessageList";
+import type { TranscriptMessage } from "../../../lib/types";
+
+const at = "2026-10-13T08:00:00.000Z";
+const user = (text: string): TranscriptMessage =>
+  ({
+    type: "user",
+    sender: "user",
+    timestamp: at,
+    content: [{ type: "text", text }],
+  }) as TranscriptMessage;
+const ask = (id: string, questions: string[]): TranscriptMessage =>
+  ({
+    type: "assistant",
+    sender: "assistant",
+    timestamp: at,
+    content: [
+      { type: "tool_use", id: `${id}r`, name: "Read", input: { file_path: "/w/a.ts" } },
+      {
+        type: "tool_use",
+        id,
+        name: "AskUserQuestion",
+        input: {
+          questions: questions.map((question) => ({
+            question,
+            header: "Pick",
+            options: [{ label: "Yes" }, { label: "No" }],
+          })),
+        },
+      },
+    ],
+  }) as TranscriptMessage;
+const result = (id: string, extra: Record<string, unknown>) =>
+  ({
+    type: "user",
+    sender: "tool",
+    timestamp: at,
+    content: [{ type: "tool_result", id, output: "x", ...extra }],
+  }) as TranscriptMessage;
+
+describe("an AskUserQuestion card", () => {
+  it("shows each question with the user's answer, outside the work line", () => {
+    render(
+      <MessageList
+        loading={false}
+        messages={[
+          user("go"),
+          ask("q1", ["Commit?", "Push?"]),
+          result("q1", { answers: { "Commit?": "Yes", "Push?": "only after review" } }),
+        ]}
+      />
+    );
+    const card = screen.getByTestId("chat-ask");
+    expect(within(card).getByText("Commit?")).toBeTruthy();
+    expect(within(card).getByText("Yes")).toBeTruthy();
+    expect(within(card).getByText("only after review")).toBeTruthy();
+    expect(within(screen.getByTestId("chat-tools")).queryByText(/Commit\?/)).toBeNull();
+  });
+
+  it("drops the (Recommended) marker from a picked answer", () => {
+    render(
+      <MessageList
+        loading={false}
+        messages={[
+          user("go"),
+          ask("q1", ["Commit?", "Tools?"]),
+          result("q1", {
+            answers: { "Commit?": "Yes (Recommended)", "Tools?": "Lint (Recommended), Test" },
+          }),
+        ]}
+      />
+    );
+    const card = screen.getByTestId("chat-ask");
+    expect(within(card).getByText("Yes")).toBeTruthy();
+    expect(within(card).getByText("Lint, Test")).toBeTruthy();
+    expect(within(card).queryByText(/Recommended/)).toBeNull();
+  });
+
+  it("says declined when refused, and shows no answer while still asked", () => {
+    const { rerender } = render(
+      <MessageList loading={false} messages={[user("go"), ask("q1", ["Commit?"])]} />
+    );
+    const card = screen.getByTestId("chat-ask");
+    expect(within(card).getByText("Commit?")).toBeTruthy();
+    expect(within(card).queryByText(/declined/i)).toBeNull();
+    rerender(
+      <MessageList
+        loading={false}
+        messages={[user("go"), ask("q1", ["Commit?"]), result("q1", { is_error: true })]}
+      />
+    );
+    expect(within(screen.getByTestId("chat-ask")).getByText(/declined/i)).toBeTruthy();
+  });
+});

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,133 @@
+/**
+ * @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; any other
+ * dropped file is a chip that opens its preview, and any other path stays 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], files: [] });
+    // 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],
+      files: [],
+    });
+    // Any other dropped file comes out by its full path.
+    const pdf = "/tmp/agenthub-drops-1001/0123456789abcdef-spec.pdf";
+    expect(splitDropImages(`read ${pdf}`)).toEqual({ text: "read", images: [], files: [pdf] });
+    // Not a drop: left as typed.
+    for (const text of ["/home/me/shot.png", "/home/me/0123456789abcdef-spec.pdf"]) {
+      expect(splitDropImages(text)).toEqual({ text, images: [], files: [] });
+    }
+  });
+
+  it("shows a dropped file as a chip that opens its preview", () => {
+    const pdf = "/home/me/.claude/agenthub/drops/0123456789abcdef-spec.pdf";
+    const opened: string[] = [];
+    const messages = [
+      {
+        type: "user",
+        sender: "user",
+        timestamp: "2026-10-09T08:00:00.000Z",
+        content: [{ type: "text", text: `summarise ${pdf}` }],
+      },
+    ] as TranscriptMessage[];
+    render(<MessageList messages={messages} loading={false} onOpenFile={(p) => opened.push(p)} />);
+
+    const bubble = screen.getByTestId("chat-user");
+    expect(bubble).not.toHaveTextContent("0123456789abcdef");
+    fireEvent.click(screen.getByRole("button", { name: /spec\.pdf/ }));
+    expect(opened).toEqual([pdf]);
+  });
+
+  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

@@ -4,12 +4,13 @@
  * 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.
+ * 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 { fireEvent, render, screen } from "@testing-library/react";
-import { MessageList, workLabel } from "../MessageList";
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { MessageList, turnStats, workLabel, workingOn } from "../MessageList";
 import type { TranscriptMessage } from "../../../lib/types";
 
 function msg(partial: Partial<TranscriptMessage>): TranscriptMessage {
@@ -22,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" }] }),
@@ -76,5 +92,255 @@ describe("MessageList — sender attribution", () => {
       "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",
+        timestamp: new Date(Date.now() - 65_000).toISOString(),
+        content: [{ type: "text", text: "test it" }],
+      }),
+      msg({
+        type: "assistant",
+        sender: "assistant",
+        timestamp: new Date(Date.now() - 5_000).toISOString(),
+        usage: { input_tokens: 2, output_tokens: 3500 },
+        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");
+    // Like the terminal: the turn's time since the prompt, and its output.
+    expect(row).toHaveTextContent(/\(1m \ds · ↑ 3\.5K tokens\)/);
+    // 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();
+  });
+
+  // Issue #74: Esc before the model wrote anything takes the prompt back into
+  // Claude Code's input box and writes NO "[Request interrupted…]" line — the
+  // transcript still ends on the prompt, which read as "Thinking…" for 15 min.
+  it("drops Thinking… once Stop was pressed, until the transcript moves on", () => {
+    const prompt = msg({
+      sender: "user",
+      timestamp: new Date(Date.now() - 14_000).toISOString(),
+      content: [{ type: "text", text: "Phần đề xuất trong báo cáo" }],
+    });
+    const { rerender } = render(<MessageList loading={false} messages={[prompt]} live />);
+    expect(screen.getByTestId("chat-running-step")).toHaveTextContent("Thinking");
+    rerender(<MessageList loading={false} messages={[prompt]} live stopped={1} />);
+    expect(screen.queryByTestId("chat-running-step")).toBeNull();
+    // The next prompt is a new turn: its Thinking… shows.
+    const next = msg({
+      sender: "user",
+      timestamp: new Date().toISOString(),
+      content: [{ type: "text", text: "again" }],
+    });
+    rerender(<MessageList loading={false} messages={[prompt, next]} live stopped={1} />);
+    expect(screen.getByTestId("chat-running-step")).toHaveTextContent("Thinking");
+  });
+
+  it("counts a turn's output once per API call, since its prompt", () => {
+    const at = "2026-06-26T08:19:00.000Z";
+    const line = (cache: number, out: number) =>
+      msg({
+        type: "assistant",
+        sender: "assistant",
+        content: [{ type: "text", text: "x" }],
+        usage: { input_tokens: 2, output_tokens: out, cache_read_input_tokens: cache },
+      });
+    const messages = [
+      msg({ sender: "user" }),
+      line(10, 999), // an earlier turn
+      msg({ sender: "user", timestamp: at }),
+      line(100, 40),
+      line(100, 40), // the same call's second block
+      msg({ sender: "tool", content: [{ type: "tool_result", id: "t", output: "ok" }] }),
+      line(200, 25),
+    ];
+    expect(turnStats(messages)).toEqual({ start: at, output: 65 });
+  });
+
+  it("keeps every parallel call of the turn running until its own result", () => {
+    const at = "2026-06-26T08:19:00.000Z";
+    const now = Date.parse("2026-06-26T08:20:00.000Z");
+    const call = (id: string) =>
+      msg({
+        type: "assistant",
+        sender: "assistant",
+        timestamp: at,
+        stop_reason: "tool_use",
+        content: [{ type: "tool_use", id, name: "Bash", input: { command: id } }],
+      });
+    const done = (id: string) =>
+      msg({ sender: "tool", timestamp: at, content: [{ type: "tool_result", id, output: "ok" }] });
+    // Claude Code writes each parallel call on its own line; one result is in.
+    const m = [msg({ sender: "user", timestamp: at }), call("a"), call("b"), call("c"), done("b")];
+    const results = new Map([["b", m[4]!.content[0]!]]);
+    expect(workingOn(m, results, now)?.blocks.map((b) => b.id)).toEqual(["a", "c"]);
+    // A call left unpaired in an EARLIER turn is not this one's.
+    const next = [
+      ...m,
+      msg({ sender: "user", timestamp: at, content: [{ type: "text", text: "go" }] }),
+    ];
+    expect(workingOn(next, results, now)?.blocks).toEqual([]);
+  });
+
+  it("says when the CLI waits on the user, and offers the terminal", () => {
+    let opened = 0;
+    render(
+      <MessageList
+        loading={false}
+        live
+        waiting
+        onOpenTerminal={() => opened++}
+        messages={[
+          msg({ sender: "user", timestamp: new Date().toISOString() }),
+          msg({
+            type: "assistant",
+            sender: "assistant",
+            timestamp: new Date().toISOString(),
+            content: [
+              { type: "tool_use", id: "t1", name: "Bash", input: { description: "Delete build" } },
+            ],
+          }),
+        ]}
+      />
+    );
+    const row = screen.getByTestId("chat-running-step");
+    expect(row).toHaveTextContent("Waiting for your approval: Delete build");
+    fireEvent.click(screen.getByTestId("chat-open-terminal"));
+    expect(opened).toBe(1);
+  });
+
+  it("closes an ended turn with its time and output", () => {
+    const reply = (out: number, stop_reason: string) =>
+      msg({
+        type: "assistant",
+        sender: "assistant",
+        timestamp: "2026-06-26T08:16:08.000Z",
+        stop_reason,
+        usage: { input_tokens: 5, output_tokens: out, cache_read_input_tokens: out },
+        content: [{ type: "text", text: "done" }],
+      });
+    render(
+      <MessageList
+        loading={false}
+        messages={[msg({ sender: "user" }), reply(1000, "tool_use"), reply(2500, "end_turn")]}
+      />
+    );
+    expect(screen.getByTestId("chat-turn-done")).toHaveTextContent("Done in 2m 8s · ↑ 3.5K tokens");
+  });
+
+  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);
+
+    const thinking = { blocks: [], since: null, last: at };
+    expect(state([prompt])).toEqual(thinking); // thinking on the prompt
+    expect(state([prompt, call])?.blocks.map((b) => b.id)).toEqual(["t1"]); // the call is running
+    expect(state([prompt, call, result])).toEqual(thinking); // thinking again
+    expect(state([prompt, call, result, reply("tool_use")])?.blocks).toEqual([]); // 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,16 +1,21 @@
 /**
  * @file AddLaneModal.tsx
- * @description The "+ Add lane" flow, in one of two modes chosen with a
+ * @description The "+ Add lane" flow, in one of three modes chosen with a
  * 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
- * manually-typed branch name. The user also picks which CLI drives the lane
- * (Claude Code or Codex) — this choice is immutable after creation. Either
+ * manually-typed branch name; "Clone" runs `POST /api/lanes/clone` (an
+ * https/ssh URL cloned into a folder of the user's, with their OWN SSH key or
+ * HTTPS login — a 409 `ECREDENTIALS` opens a login row, `ESSHAUTH` points to
+ * Settings → Git). There is no AI tool picker: the lane is created with the
+ * default AI tool (Settings → AI Tools), and each new session picks its own
+ * AI on the workspace home. 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
@@ -20,7 +25,7 @@
 
 import { useCallback, useEffect, useId, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { ChevronDown, X } from "lucide-react";
+import { X } from "lucide-react";
 import { useDialog } from "../../hooks/useDialog";
 import { CwdAutocomplete } from "../run/RunSetup";
 import { PathPickButton } from "../PathPickButton";
@@ -28,7 +33,7 @@ import { api } from "../../lib/api";
 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
@@ -46,6 +51,17 @@ async function waitForProvisioned(
   }
 }
 
+/** The folder `git clone <url>` would make: the last path segment, no `.git`. */
+export function cloneDirName(url: string): string {
+  return (
+    url
+      .trim()
+      .replace(/[/:]+$/, "")
+      .split(/[/:]/)
+      .pop() || ""
+  ).replace(/\.git$/i, "");
+}
+
 /** One segment of a two-way inline choice, styled to match RunSetup's `Seg`. */
 function Seg({
   active,
@@ -95,7 +111,18 @@ export function AddLaneModal({
   cwdSuggestions: CwdSuggestion[];
 }) {
   const { t } = useTranslation(["lanes"]);
-  const [mode, setMode] = useState<"repo" | "worktree">("repo");
+  const [mode, setMode] = useState<"repo" | "worktree" | "clone">("repo");
+  // Clone mode: the URL, the folder name (blank = the URL's), and — once the
+  // server asked for one — a login for the URL's https host.
+  const [cloneUrl, setCloneUrl] = useState("");
+  const [cloneName, setCloneName] = useState("");
+  const [login, setLogin] = useState<{
+    host: string;
+    username: string;
+    token: string;
+    remember: boolean;
+  } | null>(null);
+  const [sshRefused, setSshRefused] = useState(false);
   const [sourceRepo, setSourceRepo] = useState("");
   const [title, setTitle] = useState("");
   const [branch, setBranch] = useState("");
@@ -108,20 +135,18 @@ export function AddLaneModal({
   const [branchMode, setBranchMode] = useState<"new" | "existing">("new");
   const [base, setBase] = useState("");
   const [branchesError, setBranchesError] = useState<string | null>(null);
-  // null = the default AI tool (Settings → AI Tools), resolved at submit time.
-  const [pickedTool, setPickedTool] = useState<string | null>(null);
+  // No picker: a workspace's tool is only its DEFAULT — each new session
+  // picks its own AI on the workspace home. This is the default AI tool
+  // (Settings → AI Tools), the account's own pick first while it is
+  // installed and on.
   const aiTools = useAiTools();
-  const defaultTool = aiTools.defaultId ?? "claude";
-  const tool = pickedTool ?? defaultTool;
-  // Installed + enabled, the default first.
-  const toolChoices = aiTools.tools
-    .filter((x) => x.installed && x.enabled)
-    .sort((a, b) => Number(b.id === defaultTool) - Number(a.id === defaultTool));
-  const [toolListOpen, setToolListOpen] = useState(false);
-  const pickTool = (id: string) => {
-    setPickedTool(id === defaultTool ? null : id);
-    setToolListOpen(false);
-  };
+  const ownTool = readDefaultTool();
+  const tool =
+    (ownTool && aiTools.tools.some((x) => x.id === ownTool && x.installed && x.enabled)
+      ? ownTool
+      : null) ??
+    aiTools.defaultId ??
+    "claude";
   const noTools = aiTools.loaded && aiTools.defaultId === null;
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -132,6 +157,10 @@ export function AddLaneModal({
 
   const reset = () => {
     setMode("repo");
+    setCloneUrl("");
+    setCloneName("");
+    setLogin(null);
+    setSshRefused(false);
     setSourceRepo("");
     setTitle("");
     setBranch("");
@@ -139,7 +168,6 @@ export function AddLaneModal({
     setWorktrees([]);
     setBranchMode("new");
     setBase("");
-    setPickedTool(null);
     setBranchesError(null);
     setError(null);
     setBusy(false);
@@ -204,6 +232,52 @@ export function AddLaneModal({
     setBusy(true);
     setError(null);
 
+    if (mode === "clone") {
+      const url = cloneUrl.trim();
+      if (!url) return;
+      setSshRefused(false);
+      try {
+        const result = await api.lanes.clone({
+          url,
+          parent: repo,
+          name: cloneName.trim() || undefined,
+          title: name || undefined,
+          tool,
+          ...(login?.username.trim() && login.token
+            ? {
+                credentials: {
+                  username: login.username.trim(),
+                  password: login.token,
+                  remember: login.remember,
+                },
+              }
+            : {}),
+        });
+        onAdded(result.lane);
+        reset();
+        onClose();
+      } catch (err) {
+        const e = err as { code?: string; auth?: { host?: string }; message?: string };
+        const host = e.auth?.host || url;
+        if (e.code === "ECREDENTIALS") {
+          setError(t(login?.token ? "clone.loginRejected" : "clone.loginNeeded", { host }));
+          setLogin((l) => ({
+            host,
+            username: l?.username ?? "",
+            token: "",
+            remember: l?.remember ?? true,
+          }));
+        } else if (e.code === "ESSHAUTH") {
+          setSshRefused(true);
+          setError(t("clone.sshRefused", { host }));
+        } else {
+          setError(err instanceof Error ? err.message : String(err));
+        }
+        setBusy(false);
+      }
+      return;
+    }
+
     if (mode === "repo") {
       try {
         const result = await api.lanes.ensure({
@@ -328,6 +402,8 @@ export function AddLaneModal({
   const disabled =
     !done &&
     (!sourceRepo.trim() ||
+      (mode === "clone" &&
+        (!cloneUrl.trim() || (!!login && (!login.username.trim() || !login.token)))) ||
       (mode === "worktree" &&
         (!title.trim() || !branches?.length || (branchMode === "existing" && !branch.trim()))));
 
@@ -355,6 +431,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">
@@ -383,73 +460,57 @@ export function AddLaneModal({
               title={t("mode.worktreeHint")}
               onClick={() => setMode("worktree")}
             />
+            <Seg
+              active={mode === "clone"}
+              label={t("mode.clone")}
+              title={t("mode.cloneHint")}
+              onClick={() => setMode("clone")}
+            />
           </div>
 
-          <div>
-            <label className="mb-1 block text-xs text-fg-secondary">{t("addLaneToolHint")}</label>
-            {noTools ? (
-              <p className="rounded-md border border-status-warning/40 bg-status-warning/10 px-2 py-1.5 text-xs text-status-warning">
-                {t("addLaneNoTools")}{" "}
-                <a href="/settings/agents" className="underline">
-                  {t("addLaneNoToolsLink")}
-                </a>
-              </p>
-            ) : (
-              <div>
-                <button
-                  type="button"
-                  aria-expanded={toolListOpen}
-                  disabled={toolChoices.length < 2}
-                  onClick={() => setToolListOpen((o) => !o)}
-                  className="flex w-full items-center gap-2 rounded-md border border-border bg-surface-2 px-2.5 py-1.5 text-left text-sm text-fg-primary hover:bg-surface-3 disabled:cursor-default disabled:hover:bg-surface-2"
-                >
-                  <AiToolIcon tool={{ id: tool, label: aiTools.label(tool) }} className="h-5 w-5" />
-                  <span className="min-w-0 flex-1 truncate">{aiTools.label(tool)}</span>
-                  {tool === defaultTool && (
-                    <span className="rounded-full bg-accent/15 px-2 py-0.5 text-[10px] font-medium text-accent">
-                      {t("addLaneToolDefaultBadge")}
-                    </span>
-                  )}
-                  {toolChoices.length > 1 && (
-                    <ChevronDown
-                      aria-hidden
-                      className={`h-4 w-4 text-fg-muted transition-transform ${toolListOpen ? "rotate-180" : ""}`}
-                    />
-                  )}
-                </button>
-                {toolListOpen && (
-                  <div
-                    role="group"
-                    aria-label={t("addLaneToolHint")}
-                    className="mt-1.5 grid grid-cols-2 gap-1.5 sm:grid-cols-3"
-                  >
-                    {toolChoices.map((x) => (
-                      <button
-                        key={x.id}
-                        type="button"
-                        aria-pressed={x.id === tool}
-                        onClick={() => pickTool(x.id)}
-                        className={`flex items-center gap-2 rounded-md border px-2 py-1.5 text-left text-xs transition-colors ${
-                          x.id === tool
-                            ? "border-accent bg-accent/10 text-accent"
-                            : "border-border bg-surface-2 text-fg-secondary hover:bg-surface-3 hover:text-fg-primary"
-                        }`}
-                      >
-                        <AiToolIcon tool={x} className="h-5 w-5" />
-                        <span className="min-w-0 flex-1 truncate">{x.label}</span>
-                      </button>
-                    ))}
-                  </div>
-                )}
-              </div>
-            )}
-          </div>
+          {mode === "clone" && (
+            <div>
+              <label className="mb-1 block text-xs text-fg-secondary" htmlFor="add-lane-url">
+                {t("clone.urlLabel")}
+              </label>
+              <input
+                id="add-lane-url"
+                value={cloneUrl}
+                onChange={(e) => {
+                  setCloneUrl(e.target.value);
+                  // A login belongs to the host it was asked for.
+                  setLogin(null);
+                  setSshRefused(false);
+                }}
+                placeholder="https://github.com/owner/repo.git"
+                spellCheck={false}
+                autoComplete="off"
+                className="w-full rounded-md border border-border-light bg-surface-0 px-3 py-1.5 font-mono text-xs text-fg-primary placeholder:text-fg-muted focus:border-accent focus:outline-none"
+              />
+              <p className="mt-1 text-[10px] text-fg-muted">{t("clone.urlHint")}</p>
+            </div>
+          )}
+
+          {noTools && (
+            <p className="rounded-md border border-status-warning/40 bg-status-warning/10 px-2 py-1.5 text-xs text-status-warning">
+              {t("addLaneNoTools")}{" "}
+              <a href="/settings/agents" className="underline">
+                {t("addLaneNoToolsLink")}
+              </a>
+            </p>
+          )}
 
           <div>
             <label className="mb-1 block text-xs text-fg-secondary" htmlFor="add-lane-repo">
-              {mode === "repo" ? t("addLaneRepoLabelAdopt") : t("addLaneRepoLabel")}
+              {mode === "repo"
+                ? t("addLaneRepoLabelAdopt")
+                : mode === "clone"
+                  ? t("clone.parentLabel")
+                  : t("addLaneRepoLabel")}
             </label>
-            <div className="flex gap-1.5">
+            <div className="flex gap-1.5" data-tour="add-lane-folder">
+              {/* A click into the path only focuses it — the picker opens from
+                Browse alone (#77). */}
               <div className="min-w-0 flex-1">
                 <CwdAutocomplete
                   inputId="add-lane-repo"
@@ -461,10 +522,67 @@ export function AddLaneModal({
               <PathPickButton start={sourceRepo} onPick={setSourceRepo} showLabel />
             </div>
             <p className="mt-1 text-[10px] text-fg-muted">
-              {mode === "repo" ? t("addLaneRepoHintAdopt") : t("addLaneRepoHint")}
+              {mode === "clone"
+                ? t("clone.parentHint", {
+                    path: `${sourceRepo.trim().replace(/[\\/]+$/, "") || "…"}/${
+                      cloneName.trim() || cloneDirName(cloneUrl) || "…"
+                    }`,
+                  })
+                : mode === "repo"
+                  ? t("addLaneRepoHintAdopt")
+                  : t("addLaneRepoHint")}
             </p>
           </div>
 
+          {mode === "clone" && (
+            <div>
+              <label className="mb-1 block text-xs text-fg-secondary" htmlFor="add-lane-clone-name">
+                {t("clone.nameLabel")}
+              </label>
+              <input
+                id="add-lane-clone-name"
+                value={cloneName}
+                onChange={(e) => setCloneName(e.target.value)}
+                placeholder={cloneDirName(cloneUrl)}
+                spellCheck={false}
+                className="w-full rounded-md border border-border-light bg-surface-0 px-3 py-1.5 font-mono text-xs text-fg-primary placeholder:text-fg-muted focus:border-accent focus:outline-none"
+              />
+            </div>
+          )}
+
+          {mode === "clone" && login && (
+            <div
+              data-testid="add-lane-clone-login"
+              className="grid gap-2 rounded-md border border-border-light bg-surface-0 p-2 sm:grid-cols-2"
+            >
+              <input
+                aria-label={t("clone.username")}
+                placeholder={t("clone.username")}
+                autoComplete="off"
+                value={login.username}
+                onChange={(e) => setLogin({ ...login, username: e.target.value })}
+                className="rounded-md border border-border-light bg-surface-1 px-2 py-1 text-xs text-fg-primary placeholder:text-fg-muted focus:border-accent focus:outline-none"
+              />
+              <input
+                type="password"
+                aria-label={t("clone.token")}
+                placeholder={t("clone.token")}
+                autoComplete="new-password"
+                value={login.token}
+                onChange={(e) => setLogin({ ...login, token: e.target.value })}
+                className="rounded-md border border-border-light bg-surface-1 px-2 py-1 text-xs text-fg-primary placeholder:text-fg-muted focus:border-accent focus:outline-none"
+              />
+              <label className="flex items-center gap-1.5 text-[11px] text-fg-secondary sm:col-span-2">
+                <input
+                  type="checkbox"
+                  checked={login.remember}
+                  onChange={(e) => setLogin({ ...login, remember: e.target.checked })}
+                />
+                {t("clone.remember")}
+              </label>
+            </div>
+          )}
+
           {/* What this repo already has checked out. Without it the form asked
             for a branch in the dark: the one fact that decides whether a
             branch can be used at all is which worktree is holding it. */}
@@ -678,6 +796,14 @@ export function AddLaneModal({
           {error && (
             <p role="alert" className="text-xs text-status-danger">
               {error}
+              {sshRefused && (
+                <>
+                  {" "}
+                  <a href="/settings/git#git-identity" className="underline">
+                    {t("clone.sshSettings")}
+                  </a>
+                </>
+              )}
             </p>
           )}
         </div>
@@ -695,9 +821,14 @@ 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")}
+            {done
+              ? t("addLaneSetupClose")
+              : busy && mode === "clone"
+                ? t("clone.cloning")
+                : t("add")}
           </button>
         </div>
       </div>

client/src/components/lanes/CloneSourcesForm.tsx

@@ -0,0 +1,188 @@
+/**
+ * @file CloneSourcesForm — a workspace's "Or clone repositories" box, under
+ * its Folders card: one URL per line, each cloned BESIDE the workspace folder
+ * (`POST /api/lanes/:id/sources/clone`, the server picks the folder) and
+ * added as an extra folder, one after another. A host that wants a login
+ * (409 `ECREDENTIALS`) opens one login row; Retry re-runs only the failed
+ * URLs with it, like Add workspace → Clone.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useState } from "react";
+import { useTranslation } from "react-i18next";
+import { Check, Loader2, X } from "lucide-react";
+import { api, type LaneSourcesView } from "../../lib/api";
+
+type Row = { url: string; state: "wait" | "busy" | "done" | "failed"; note?: string };
+type Login = { host: string; username: string; token: string; remember: boolean };
+
+export function CloneSourcesForm({
+  laneId,
+  parent,
+  onAdded,
+}: {
+  laneId: number;
+  /** Where the clones land: the workspace folder's parent, shown only. */
+  parent: string;
+  onAdded: (view: LaneSourcesView) => void;
+}) {
+  const { t } = useTranslation("lanes");
+  const [text, setText] = useState("");
+  const [rows, setRows] = useState<Row[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [login, setLogin] = useState<Login | null>(null);
+
+  const urls = (s: string) => [
+    ...new Set(
+      s
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+    ),
+  ];
+
+  const cloneAll = async (list: string[]) => {
+    if (busy || !list.length) return;
+    setBusy(true);
+    const next: Row[] = list.map((url) => ({ url, state: "wait" }));
+    const show = () => setRows([...next]);
+    show();
+    let asked: Login | null = null;
+    for (const row of next) {
+      row.state = "busy";
+      show();
+      try {
+        const view = await api.lanes.cloneFolder(laneId, {
+          url: row.url,
+          ...(login?.username.trim() && login.token
+            ? {
+                credentials: {
+                  username: login.username.trim(),
+                  password: login.token,
+                  remember: login.remember,
+                },
+              }
+            : {}),
+        });
+        row.state = "done";
+        onAdded(view);
+      } catch (err) {
+        const e = err as { code?: string; auth?: { host?: string }; message?: string };
+        const host = e.auth?.host || row.url;
+        row.state = "failed";
+        if (e.code === "ECREDENTIALS") {
+          row.note = t(login?.token ? "clone.loginRejected" : "clone.loginNeeded", { host });
+          asked ??= {
+            host,
+            username: login?.username ?? "",
+            token: "",
+            remember: login?.remember ?? true,
+          };
+        } else if (e.code === "ESSHAUTH") {
+          row.note = t("clone.sshRefused", { host });
+        } else {
+          row.note = e.message || String(err);
+        }
+      }
+      show();
+    }
+    if (asked) setLogin(asked);
+    // What is left to do stays in the box; what was added leaves it.
+    setText(
+      next
+        .filter((r) => r.state !== "done")
+        .map((r) => r.url)
+        .join("\n")
+    );
+    setBusy(false);
+  };
+
+  const failed = rows.filter((r) => r.state === "failed").map((r) => r.url);
+
+  return (
+    <div className="space-y-2 border-t border-border-light pt-2" data-testid="workspace-clone">
+      <p className="text-[10px] uppercase tracking-wide text-fg-muted">{t("home.cloneFolders")}</p>
+      <textarea
+        data-testid="workspace-clone-input"
+        aria-label={t("home.cloneFolders")}
+        placeholder={t("home.clonePlaceholder")}
+        rows={3}
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        className="w-full rounded border border-border bg-surface-1 px-2 py-1 font-mono text-[11px] text-fg-primary"
+      />
+      <p className="text-[11px] text-fg-muted">{t("home.cloneHint", { path: parent })}</p>
+      {login && (
+        <div className="space-y-1.5 rounded border border-border-light p-2">
+          <div className="flex gap-2">
+            <input
+              aria-label={t("clone.username")}
+              placeholder={t("clone.username")}
+              value={login.username}
+              onChange={(e) => setLogin({ ...login, username: e.target.value })}
+              className="min-w-0 flex-1 rounded border border-border bg-surface-1 px-2 py-1 text-[11px] text-fg-primary"
+            />
+            <input
+              type="password"
+              aria-label={t("clone.token")}
+              placeholder={t("clone.token")}
+              value={login.token}
+              onChange={(e) => setLogin({ ...login, token: e.target.value })}
+              className="min-w-0 flex-1 rounded border border-border bg-surface-1 px-2 py-1 text-[11px] text-fg-primary"
+            />
+          </div>
+          <label className="flex items-center gap-1.5 text-[11px] text-fg-secondary">
+            <input
+              type="checkbox"
+              checked={login.remember}
+              onChange={(e) => setLogin({ ...login, remember: e.target.checked })}
+            />
+            {t("clone.remember")}
+          </label>
+        </div>
+      )}
+      <div className="flex justify-end gap-2">
+        {failed.length > 0 && !busy && (
+          <button type="button" onClick={() => void cloneAll(failed)} className="btn-ghost text-xs">
+            {t("home.cloneRetry")}
+          </button>
+        )}
+        <button
+          type="button"
+          data-testid="workspace-clone-run"
+          disabled={busy || !urls(text).length}
+          onClick={() => void cloneAll(urls(text))}
+          className="btn-ghost text-xs"
+        >
+          {busy ? t("clone.cloning") : t("home.cloneRun")}
+        </button>
+      </div>
+      {rows.length > 0 && (
+        <ul className="space-y-1" data-testid="workspace-clone-rows">
+          {rows.map((r) => (
+            <li key={r.url} className="text-[11px]">
+              <span className="flex items-center gap-1.5">
+                {r.state === "busy" ? (
+                  <Loader2 className="h-3 w-3 shrink-0 animate-spin text-fg-muted" />
+                ) : r.state === "done" ? (
+                  <Check
+                    className="h-3 w-3 shrink-0 text-status-success"
+                    aria-label={t("home.cloneDone")}
+                  />
+                ) : r.state === "failed" ? (
+                  <X className="h-3 w-3 shrink-0 text-status-danger" />
+                ) : (
+                  <span className="h-3 w-3 shrink-0" />
+                )}
+                <span className="min-w-0 truncate font-mono text-fg-secondary" title={r.url}>
+                  {r.url}
+                </span>
+              </span>
+              {r.note && <span className="ml-[18px] block text-status-danger">{r.note}</span>}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

client/src/components/lanes/DiffEditor.tsx

@@ -21,7 +21,7 @@
  * 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 at the end of its first line (inline, so it covers no code),
+ * 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.
@@ -50,6 +50,8 @@ import {
   highlightActiveLineGutter,
   keymap,
   lineNumbers,
+  showTooltip,
+  type Tooltip,
   type DecorationSet,
   type ViewUpdate,
 } from "@codemirror/view";
@@ -284,41 +286,34 @@ function blockBars(orig: Text, build: (b: EditorBlock) => HTMLElement) {
   });
 }
 
-class ChatChip extends WidgetType {
-  constructor(
-    readonly start: number,
-    readonly end: number,
-    readonly build: (start: number, end: number) => HTMLElement
-  ) {
-    super();
-  }
-  eq(o: ChatChip) {
-    return this.start === o.start && this.end === o.end;
-  }
-  toDOM() {
-    return this.build(this.start, this.end);
-  }
-}
-
-/** Add to Chat inline at the end of a non-empty selection's first line —
- *  the empty space right of the code, so it covers no line. `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. */
+/** 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<DecorationSet>({
-    create: () => Decoration.none,
-    update(deco, tr) {
-      if (!tr.docChanged && !tr.selection) return deco;
+  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 Decoration.none;
+      if (empty) return null;
       const doc = tr.state.doc;
       const first = doc.lineAt(from);
       const last = doc.lineAt(to);
-      const end = to === last.from && last.number > first.number ? last.number - 1 : last.number;
-      const widget = new ChatChip(first.number, end, build);
-      return Decoration.set(Decoration.widget({ widget, side: 1 }).range(first.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) => EditorView.decorations.from(f),
+    provide: (f) => showTooltip.from(f),
   });
 }
 
@@ -355,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" },
@@ -544,7 +549,7 @@ export default function DiffEditor({
               b.dataset.testid = "lane-editor-add-to-chat";
               b.textContent = cb.current.t("changes.addToChat");
               b.className =
-                "ml-3 rounded border border-accent/60 bg-surface-1 px-1.5 font-sans text-[10px] leading-[14px] text-accent align-middle hover:bg-surface-2";
+                "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);

client/src/components/lanes/FolderBrowseModal.tsx

@@ -1,46 +1,178 @@
 /**
- * @file A server-backed folder browser for the Add Lane modal's path inputs.
- * Browsers refuse to expose an absolute filesystem path from a native folder
- * picker, so path selection here is done by browsing `GET /api/lanes/browse`
- * (immediate subdirectories of a path) instead — breadcrumb-free, just an
- * up-one-level button and a click-to-descend list, since this tool is
- * local-first and the server already trusts arbitrary local paths.
+ * @file A server-backed folder (or file) browser for the path inputs' Browse
+ * button, laid out like the OS's own picker. Browsers refuse to expose an
+ * absolute filesystem path from a native picker, so path selection here is
+ * done by browsing `GET /api/lanes/browse` instead: back/forward/up, a
+ * clickable breadcrumb that turns into a path field (Ctrl+L), a Places column
+ * (Home, the user's workspaces, recent picks), a filter, Name/Modified columns,
+ * hidden entries on demand and New folder (`POST /api/lanes/browse/mkdir`).
+ * A click selects, a double-click or Enter opens a folder (picks a file),
+ * Backspace goes up and typing jumps to a name.
+ * An admin with a Linux account of their own (S3; the listing carries
+ * `hostHome`) opens in THEIR home; the "Server folder" tick switches the
+ * browser to the host account's home, where a workspace runs as the shared
+ * host account. It is never remembered: every open starts at the admin's own.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState, type KeyboardEvent } from "react";
 import { useTranslation } from "react-i18next";
-import { FolderOpen, FolderGit2, ArrowUp } from "lucide-react";
+import {
+  ArrowLeft,
+  ArrowRight,
+  ArrowUp,
+  Clock,
+  Eye,
+  File,
+  FolderGit2,
+  FolderOpen,
+  FolderPlus,
+  Home,
+  Pencil,
+  Server,
+  Star,
+} from "lucide-react";
 import { api } from "../../lib/api";
+import { formatDateTime } from "../../lib/format";
+import { isSubmitEnter } from "../../lib/keys";
 import { useDialog } from "../../hooks/useDialog";
+import { useWorkLanes } from "../../hooks/useLanes";
 
-export function FolderBrowseModal({
+type Listing = Awaited<ReturnType<typeof api.lanes.browse>>;
+type Entry = Listing["entries"][number];
+
+const RECENT_KEY = "agenthub.browse.recent";
+const HIDDEN_KEY = "agenthub.browse.hidden";
+const RECENT_MAX = 8;
+
+function readStored<T>(key: string, fallback: T): T {
+  try {
+    const raw = localStorage.getItem(key);
+    return raw ? (JSON.parse(raw) as T) : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeStored(key: string, value: unknown) {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    // A private window or blocked storage: the preference just isn't kept.
+  }
+}
+
+/** `[label, path]` for each level of `p`, root first. */
+function crumbs(p: string): [string, string][] {
+  const win = /^[A-Za-z]:\\/.test(p);
+  const sep = win ? "\\" : "/";
+  const parts = p.split(sep).filter(Boolean);
+  const out: [string, string][] = win ? [] : [["/", "/"]];
+  let acc = "";
+  for (const part of parts) {
+    acc = win ? (acc ? `${acc}\\${part}` : `${part}\\`) : `${acc}/${part}`;
+    out.push([part, acc]);
+  }
+  return out;
+}
+
+const baseName = (p: string) => p.split(/[\\/]/).filter(Boolean).pop() || p;
+
+type Props = {
+  open: boolean;
+  /** `file` lists files too, and picking one is the only way to select. */
+  kind?: "dir" | "file";
+  /** Path to start browsing from; omitted defaults server-side to the home dir. */
+  initialPath?: string;
+  onSelect: (path: string) => void;
+  onClose: () => void;
+};
+
+/**
+ * Mounted only while open, so a closed picker (one behind every Browse
+ * button) asks the server for nothing, and each opening starts fresh.
+ */
+export function FolderBrowseModal(props: Props) {
+  return props.open ? <BrowseDialog {...props} /> : null;
+}
+
+function BrowseDialog({
   open,
+  kind = "dir",
   initialPath,
   onSelect,
   onClose,
 }: {
   open: boolean;
+  /** `file` lists files too, and picking one is the only way to select. */
+  kind?: "dir" | "file";
   /** Path to start browsing from; omitted defaults server-side to the home dir. */
   initialPath?: string;
   onSelect: (path: string) => void;
   onClose: () => void;
 }) {
   const { t } = useTranslation(["lanes"]);
-  const [listing, setListing] = useState<Awaited<ReturnType<typeof api.lanes.browse>> | null>(null);
+  const { lanes } = useWorkLanes();
+  const [listing, setListing] = useState<Listing | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [history, setHistory] = useState<{ stack: string[]; at: number }>({ stack: [], at: -1 });
+  const [selected, setSelected] = useState<string | null>(null);
+  const [filter, setFilter] = useState("");
+  const [editing, setEditing] = useState(false);
+  const [pathText, setPathText] = useState("");
+  const [sort, setSort] = useState<{ key: "name" | "mtime"; dir: 1 | -1 }>({
+    key: "name",
+    dir: 1,
+  });
+  const [showHidden, setShowHidden] = useState(() => readStored(HIDDEN_KEY, false));
+  const [creating, setCreating] = useState(false);
+  const [newName, setNewName] = useState("");
+  const [recent, setRecent] = useState<string[]>(() => readStored(RECENT_KEY, []));
+  // The highest folder this user may open (a member's own folder answers no
+  // parent) — breadcrumbs above it are not links.
+  const [floor, setFloor] = useState<string | null>(null);
+  const [home, setHome] = useState<string | null>(null);
+  // An admin's "Server folder" tick (S3): browse the host account's home.
+  const [hostHome, setHostHome] = useState<string | null>(null);
+  const [onHost, setOnHost] = useState(false);
+  const listRef = useRef<HTMLDivElement>(null);
+  const crumbRef = useRef<HTMLDivElement>(null);
+  const typeAhead = useRef({ text: "", at: 0 });
 
-  const load = async (path?: string) => {
+  const load = async (
+    target?: string,
+    { push = true, hidden = showHidden, select = null as string | null, host = onHost } = {}
+  ) => {
     setError(null);
     try {
-      setListing(await api.lanes.browse(path));
+      const next = await api.lanes.browse(target, kind === "file", hidden, host);
+      setListing(next);
+      setSelected(select);
+      setFilter("");
+      setEditing(false);
+      if (next.home) setHome(next.home);
+      setHostHome(next.hostHome ?? null);
+      if (next.parent === null && crumbs(next.path).length > 1) setFloor(next.path);
+      if (push) {
+        setHistory((h) => {
+          if (h.stack[h.at] === next.path) return h;
+          const stack = [...h.stack.slice(0, h.at + 1), next.path];
+          return { stack, at: stack.length - 1 };
+        });
+      }
+      return true;
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err));
+      return false;
     }
   };
 
   useEffect(() => {
-    if (open) void load(initialPath);
+    if (!open) return;
+    setHistory({ stack: [], at: -1 });
+    setCreating(false);
+    setOnHost(false);
+    void load(initialPath, { host: false });
     // Only re-run when the modal actually opens - not on every initialPath
     // keystroke in the field behind it.
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -51,8 +183,171 @@ export function FolderBrowseModal({
   const panel = useRef<HTMLDivElement>(null);
   useDialog(open, panel, onClose);
 
+  const entries = useMemo(() => {
+    const needle = filter.trim().toLowerCase();
+    const list = (listing?.entries ?? []).filter(
+      (e) => !needle || e.name.toLowerCase().includes(needle)
+    );
+    const by = (a: Entry, b: Entry) =>
+      sort.key === "mtime"
+        ? ((a.mtime ?? 0) - (b.mtime ?? 0)) * sort.dir
+        : a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" }) *
+          sort.dir;
+    // Folders first, as every file picker lists them.
+    return [...list].sort((a, b) => Number(!!a.file) - Number(!!b.file) || by(a, b));
+  }, [listing, filter, sort]);
+
+  const places = useMemo(() => {
+    const seen = new Set<string>();
+    return lanes
+      .filter((l) => l.cwd && !seen.has(l.cwd) && seen.add(l.cwd))
+      .map((l) => ({ label: l.title || baseName(l.cwd), path: l.cwd }));
+  }, [lanes]);
+
+  // A deep path keeps its LAST levels in view, like a native path bar.
+  useEffect(() => {
+    const el = crumbRef.current;
+    if (el) el.scrollLeft = el.scrollWidth;
+  }, [listing?.path, editing]);
+
+  useEffect(() => {
+    if (!selected) return;
+    const el = Array.from(listRef.current?.querySelectorAll<HTMLElement>("[data-path]") ?? []).find(
+      (x) => x.dataset.path === selected
+    );
+    el?.scrollIntoView?.({ block: "nearest" });
+  }, [selected]);
+
   if (!open) return null;
 
+  const finish = (picked: string) => {
+    const folder = kind === "file" ? (listing?.path ?? picked) : picked;
+    const next = [folder, ...recent.filter((r) => r !== folder)].slice(0, RECENT_MAX);
+    setRecent(next);
+    writeStored(RECENT_KEY, next);
+    onSelect(picked);
+    onClose();
+  };
+
+  const activate = (entry: Entry) => {
+    if (entry.file) finish(entry.path);
+    else void load(entry.path);
+  };
+
+  const go = (delta: -1 | 1) => {
+    const at = history.at + delta;
+    const target = history.stack[at];
+    if (target === undefined) return;
+    void load(target, { push: false }).then((ok) => {
+      if (ok) setHistory((h) => ({ ...h, at }));
+    });
+  };
+
+  const goUp = () => {
+    if (!listing?.parent) return;
+    const from = listing.path;
+    void load(listing.parent, { select: from });
+  };
+
+  const selectedEntry = entries.find((e) => e.path === selected) ?? null;
+  const target =
+    kind === "file"
+      ? selectedEntry?.file
+        ? selectedEntry.path
+        : null
+      : selectedEntry && !selectedEntry.file
+        ? selectedEntry.path
+        : (listing?.path ?? null);
+
+  const onListKey = (e: KeyboardEvent<HTMLDivElement>) => {
+    const idx = entries.findIndex((x) => x.path === selected);
+    if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+      e.preventDefault();
+      if (e.altKey && e.key === "ArrowUp") return goUp();
+      const next =
+        e.key === "ArrowDown" ? Math.min(entries.length - 1, idx + 1) : Math.max(0, idx - 1);
+      if (entries[next]) setSelected(entries[next].path);
+      return;
+    }
+    if (e.key === "Home" || e.key === "End") {
+      e.preventDefault();
+      const pick = e.key === "Home" ? entries[0] : entries[entries.length - 1];
+      if (pick) setSelected(pick.path);
+      return;
+    }
+    if (e.key === "Enter") {
+      e.preventDefault();
+      if (selectedEntry) activate(selectedEntry);
+      else if (kind === "dir" && target) finish(target);
+      return;
+    }
+    if (e.key === "Backspace") {
+      e.preventDefault();
+      goUp();
+      return;
+    }
+    if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+      // Typing jumps to the first name that starts with what was typed.
+      const now = Date.now();
+      const ta = typeAhead.current;
+      ta.text = now - ta.at > 800 ? e.key.toLowerCase() : ta.text + e.key.toLowerCase();
+      ta.at = now;
+      const hit = entries.find((x) => x.name.toLowerCase().startsWith(ta.text));
+      if (hit) setSelected(hit.path);
+    }
+  };
+
+  const onPanelKey = (e: KeyboardEvent<HTMLDivElement>) => {
+    if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "l") {
+      e.preventDefault();
+      setPathText(listing?.path ?? "");
+      setEditing(true);
+    } else if (e.altKey && e.key === "ArrowLeft") {
+      e.preventDefault();
+      go(-1);
+    } else if (e.altKey && e.key === "ArrowRight") {
+      e.preventDefault();
+      go(1);
+    }
+  };
+
+  const createFolder = async () => {
+    const name = newName.trim();
+    if (!name || !listing) return;
+    setError(null);
+    try {
+      const made = await api.lanes.mkdir(listing.path, name);
+      setCreating(false);
+      setNewName("");
+      await load(listing.path, { push: false, select: made.path });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  };
+
+  // Switch between the admin's own home and the host account's, and open it.
+  const toggleHost = () => {
+    const next = !onHost;
+    setOnHost(next);
+    void load(undefined, { host: next });
+  };
+
+  const toggleHidden = () => {
+    const next = !showHidden;
+    setShowHidden(next);
+    writeStored(HIDDEN_KEY, next);
+    if (listing) void load(listing.path, { push: false, hidden: next, select: selected });
+  };
+
+  const iconBtn =
+    "flex h-7 w-7 items-center justify-center rounded-md text-fg-secondary hover:bg-surface-2 disabled:opacity-40 disabled:hover:bg-transparent";
+  const placeBtn = (active: boolean) =>
+    `flex w-full items-center gap-2 rounded px-2 py-1 text-left text-xs ${
+      active ? "bg-surface-2 text-fg-primary" : "text-fg-secondary hover:bg-surface-2"
+    }`;
+  const path = listing?.path ?? "";
+  const floorDepth = floor ? crumbs(floor).length : 0;
+
   return (
     <div
       className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4"
@@ -61,73 +356,362 @@ export function FolderBrowseModal({
     >
       <div
         ref={panel}
-        className="relative flex max-h-[70vh] w-full max-w-md flex-col rounded-xl border border-border bg-surface-1 shadow-xl shadow-black/40"
+        className="relative flex h-[min(80vh,640px)] w-full max-w-3xl flex-col rounded-xl border border-border bg-surface-1 shadow-xl shadow-black/40"
         onClick={(e) => e.stopPropagation()}
+        onKeyDown={onPanelKey}
         role="dialog"
         aria-modal="true"
-        aria-label={t("browse.title")}
+        aria-label={kind === "file" ? t("browse.fileTitle") : 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}>
-            {listing?.path || "…"}
+        {/* Toolbar: history, up, and the breadcrumb / path field. */}
+        <div className="flex items-center gap-1 border-b border-border p-2">
+          <button
+            type="button"
+            className={iconBtn}
+            onClick={() => go(-1)}
+            disabled={history.at <= 0}
+            title={t("browse.back")}
+            aria-label={t("browse.back")}
+          >
+            <ArrowLeft className="h-4 w-4" />
+          </button>
+          <button
+            type="button"
+            className={iconBtn}
+            onClick={() => go(1)}
+            disabled={history.at >= history.stack.length - 1}
+            title={t("browse.forward")}
+            aria-label={t("browse.forward")}
+          >
+            <ArrowRight className="h-4 w-4" />
+          </button>
+          <button
+            type="button"
+            className={iconBtn}
+            onClick={goUp}
+            disabled={!listing?.parent}
+            title={t("browse.up")}
+            aria-label={t("browse.up")}
+          >
+            <ArrowUp className="h-4 w-4" />
+          </button>
+          {editing ? (
+            <input
+              autoFocus
+              value={pathText}
+              onChange={(e) => setPathText(e.target.value)}
+              onKeyDown={(e) => {
+                if (isSubmitEnter(e)) {
+                  e.preventDefault();
+                  if (pathText.trim()) void load(pathText.trim());
+                } else if (e.key === "Escape") {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  setEditing(false);
+                }
+              }}
+              onBlur={() => setEditing(false)}
+              aria-label={t("browse.editPath")}
+              spellCheck={false}
+              className="input min-w-0 flex-1 font-mono text-xs"
+            />
+          ) : (
+            <div
+              ref={crumbRef}
+              className="flex min-w-0 flex-1 items-center overflow-x-auto rounded-md border border-border-light px-1 py-0.5"
+              onDoubleClick={() => {
+                setPathText(path);
+                setEditing(true);
+              }}
+            >
+              {crumbs(path).map(([label, p], i, all) => {
+                const last = i === all.length - 1;
+                const locked = i + 1 < floorDepth;
+                return (
+                  <span key={p} className="flex shrink-0 items-center">
+                    {i > 0 && all[i - 1]?.[0] !== "/" && (
+                      <span className="px-0.5 text-fg-muted">›</span>
+                    )}
+                    <button
+                      type="button"
+                      disabled={last || locked}
+                      onClick={() => void load(p, { select: all[i + 1]?.[1] ?? null })}
+                      className={`rounded px-1 py-0.5 font-mono text-xs ${
+                        last
+                          ? "font-medium text-fg-primary"
+                          : locked
+                            ? "text-fg-muted"
+                            : "text-fg-secondary hover:bg-surface-2"
+                      }`}
+                    >
+                      {label}
+                    </button>
+                  </span>
+                );
+              })}
+            </div>
+          )}
+          <button
+            type="button"
+            className={iconBtn}
+            onMouseDown={(e) => e.preventDefault()}
+            onClick={() => {
+              setPathText(path);
+              setEditing((v) => !v);
+            }}
+            title={t("browse.editPath")}
+            aria-label={t("browse.editPath")}
+          >
+            <Pencil className="h-3.5 w-3.5" />
+          </button>
+        </div>
+
+        <div className="flex min-h-0 flex-1">
+          {/* Places */}
+          <nav
+            className="hidden w-44 shrink-0 overflow-y-auto border-r border-border p-2 sm:block"
+            aria-label={t("browse.places")}
+          >
+            {home && (
+              <button
+                type="button"
+                className={placeBtn(path === home)}
+                onClick={() => void load(home)}
+                title={home}
+              >
+                <Home className="h-3.5 w-3.5 shrink-0" />
+                <span className="truncate">{t("browse.home")}</span>
+              </button>
+            )}
+            {places.length > 0 && (
+              <>
+                <div className="mt-3 flex items-center gap-1 px-2 pb-1 text-[10px] font-medium uppercase tracking-wide text-fg-muted">
+                  <Star className="h-3 w-3" />
+                  {t("browse.workspaces")}
+                </div>
+                {places.map((pl) => (
+                  <button
+                    key={pl.path}
+                    type="button"
+                    className={placeBtn(path === pl.path)}
+                    onClick={() => void load(pl.path)}
+                    title={pl.path}
+                  >
+                    <FolderGit2 className="h-3.5 w-3.5 shrink-0 text-accent" />
+                    <span className="truncate">{pl.label}</span>
+                  </button>
+                ))}
+              </>
+            )}
+            {recent.length > 0 && (
+              <>
+                <div className="mt-3 flex items-center gap-1 px-2 pb-1 text-[10px] font-medium uppercase tracking-wide text-fg-muted">
+                  <Clock className="h-3 w-3" />
+                  {t("browse.recent")}
+                </div>
+                {recent.map((r) => (
+                  <button
+                    key={r}
+                    type="button"
+                    className={placeBtn(path === r)}
+                    onClick={() => void load(r)}
+                    title={r}
+                  >
+                    <FolderOpen className="h-3.5 w-3.5 shrink-0" />
+                    <span className="truncate">{baseName(r)}</span>
+                  </button>
+                ))}
+              </>
+            )}
+          </nav>
+
+          {/* Listing */}
+          <div className="flex min-w-0 flex-1 flex-col">
+            <div className="flex items-center gap-2 border-b border-border p-2">
+              <input
+                value={filter}
+                onChange={(e) => setFilter(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === "ArrowDown") {
+                    e.preventDefault();
+                    if (entries[0]) setSelected(entries[0].path);
+                    listRef.current?.focus();
+                  } else if (isSubmitEnter(e) && entries.length === 1 && entries[0]) {
+                    e.preventDefault();
+                    activate(entries[0]);
+                  }
+                }}
+                placeholder={t("browse.filter")}
+                aria-label={t("browse.filter")}
+                className="input min-w-0 flex-1 text-xs"
+              />
+            </div>
+            <div className="flex items-center border-b border-border px-3 py-1 text-[10px] font-medium uppercase tracking-wide text-fg-muted">
+              {(["name", "mtime"] as const).map((key) => (
+                <button
+                  key={key}
+                  type="button"
+                  onClick={() =>
+                    setSort((s) => ({ key, dir: s.key === key ? (s.dir === 1 ? -1 : 1) : 1 }))
+                  }
+                  className={`${key === "name" ? "flex-1 text-left" : "hidden w-32 text-right sm:block"} hover:text-fg-secondary`}
+                >
+                  {key === "name" ? t("browse.name") : t("browse.modified")}
+                  {sort.key === key && (sort.dir === 1 ? " ↑" : " ↓")}
+                </button>
+              ))}
+            </div>
+            <div
+              ref={listRef}
+              tabIndex={0}
+              role="listbox"
+              aria-label={path}
+              onKeyDown={onListKey}
+              className="min-h-0 flex-1 overflow-y-auto p-1 outline-none"
+            >
+              {error && (
+                <p role="alert" className="p-2 text-xs text-status-danger">
+                  {error}
+                </p>
+              )}
+              {creating && (
+                <div className="flex items-center gap-2 px-2 py-1">
+                  <FolderPlus className="h-3.5 w-3.5 shrink-0 text-fg-muted" />
+                  <input
+                    autoFocus
+                    value={newName}
+                    onChange={(e) => setNewName(e.target.value)}
+                    onKeyDown={(e) => {
+                      e.stopPropagation();
+                      if (isSubmitEnter(e)) {
+                        e.preventDefault();
+                        void createFolder();
+                      } else if (e.key === "Escape") {
+                        e.preventDefault();
+                        setCreating(false);
+                      }
+                    }}
+                    placeholder={t("browse.newFolderName")}
+                    aria-label={t("browse.newFolderName")}
+                    className="input min-w-0 flex-1 text-xs"
+                  />
+                  <button
+                    type="button"
+                    onClick={() => void createFolder()}
+                    disabled={!newName.trim()}
+                    className="btn-primary text-xs disabled:opacity-50"
+                  >
+                    {t("browse.create")}
+                  </button>
+                </div>
+              )}
+              {entries.map((entry) => {
+                const isSel = entry.path === selected;
+                return (
+                  <div
+                    key={entry.path}
+                    data-path={entry.path}
+                    role="option"
+                    aria-selected={isSel}
+                    onClick={() => setSelected(entry.path)}
+                    onDoubleClick={() => activate(entry)}
+                    className={`flex cursor-default select-none items-center gap-2 rounded px-2 py-1.5 text-xs ${
+                      isSel ? "bg-accent-solid text-white" : "text-fg-primary hover:bg-surface-2"
+                    }`}
+                  >
+                    {entry.file ? (
+                      <File className={`h-3.5 w-3.5 shrink-0 ${isSel ? "" : "text-fg-muted"}`} />
+                    ) : entry.isGitRepo ? (
+                      <FolderGit2
+                        className={`h-3.5 w-3.5 shrink-0 ${isSel ? "" : "text-accent"}`}
+                      />
+                    ) : (
+                      <FolderOpen
+                        className={`h-3.5 w-3.5 shrink-0 ${isSel ? "" : "text-fg-muted"}`}
+                      />
+                    )}
+                    <span className="min-w-0 flex-1 truncate">{entry.name}</span>
+                    <span
+                      className={`hidden w-32 shrink-0 text-right tabular-nums sm:block ${isSel ? "" : "text-fg-muted"}`}
+                    >
+                      {entry.mtime ? formatDateTime(new Date(entry.mtime).toISOString()) : ""}
+                    </span>
+                  </div>
+                );
+              })}
+              {listing && entries.length === 0 && (
+                <p className="p-2 text-xs text-fg-muted">
+                  {filter.trim() ? t("browse.noMatch") : t("browse.empty")}
+                </p>
+              )}
+            </div>
           </div>
         </div>
 
-        <div className="flex-1 overflow-y-auto p-1">
-          {error && (
-            <p role="alert" className="p-2 text-xs text-status-danger">
-              {error}
-            </p>
-          )}
-          {listing?.parent && (
+        {/* Footer: what will be picked, and the actions. */}
+        <div className="border-t border-border p-2">
+          <div
+            // rtl so a long path loses its START to the ellipsis, not the folder.
+            className="truncate px-1 pb-2 text-left font-mono text-xs text-fg-secondary [direction:rtl]"
+            title={target ?? undefined}
+          >
+            <bdi>{target ?? "…"}</bdi>
+          </div>
+          <div className="flex flex-wrap items-center gap-2">
             <button
               type="button"
-              onClick={() => load(listing.parent!)}
-              className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-left text-xs text-fg-secondary hover:bg-surface-2"
+              onClick={() => {
+                setNewName("");
+                setCreating(true);
+              }}
+              disabled={!listing}
+              className="btn-ghost flex items-center gap-1 border border-border text-xs disabled:opacity-50"
             >
-              <ArrowUp className="h-3.5 w-3.5" />
-              ..
+              <FolderPlus className="h-3.5 w-3.5" />
+              {t("browse.newFolder")}
             </button>
-          )}
-          {listing?.entries.map((entry) => (
-            <button
-              key={entry.path}
-              type="button"
-              onClick={() => load(entry.path)}
-              className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-left text-xs text-fg-primary hover:bg-surface-2"
-            >
-              {entry.isGitRepo ? (
-                <FolderGit2 className="h-3.5 w-3.5 text-accent" />
-              ) : (
-                <FolderOpen className="h-3.5 w-3.5 text-fg-muted" />
-              )}
-              <span className="truncate">{entry.name}</span>
-            </button>
-          ))}
-          {listing && listing.entries.length === 0 && !listing.parent && (
-            <p className="p-2 text-xs text-fg-muted">{t("browse.empty")}</p>
-          )}
-        </div>
-
-        <div className="flex items-center justify-end gap-2 border-t border-border p-3">
-          <button
-            type="button"
-            onClick={onClose}
-            className="btn-ghost border border-border text-xs"
-          >
-            {t("destructive.cancel")}
-          </button>
-          <button
-            type="button"
-            disabled={!listing}
-            onClick={() => {
-              if (listing) onSelect(listing.path);
-              onClose();
-            }}
-            className="btn-primary text-xs disabled:opacity-50"
-          >
-            {t("browse.select")}
-          </button>
+            <label className="flex cursor-pointer items-center gap-1 text-xs text-fg-secondary">
+              <input type="checkbox" checked={showHidden} onChange={toggleHidden} />
+              <Eye className="h-3.5 w-3.5" />
+              {t("browse.showHidden")}
+            </label>
+            {hostHome && (
+              <label
+                className="flex cursor-pointer items-center gap-1 text-xs text-fg-secondary"
+                title={t("browse.hostFolderHint", { path: hostHome })}
+              >
+                <input
+                  type="checkbox"
+                  checked={onHost}
+                  onChange={toggleHost}
+                  data-testid="browse-host-folder"
+                />
+                <Server className="h-3.5 w-3.5" />
+                {t("browse.hostFolder")}
+              </label>
+            )}
+            <span className="hidden flex-1 truncate text-[10px] text-fg-muted md:block">
+              {t("browse.hint")}
+            </span>
+            <div className="ml-auto flex items-center gap-2">
+              <button
+                type="button"
+                onClick={onClose}
+                className="btn-ghost border border-border text-xs"
+              >
+                {t("destructive.cancel")}
+              </button>
+              <button
+                type="button"
+                disabled={!target}
+                onClick={() => target && finish(target)}
+                className="btn-primary text-xs disabled:opacity-50"
+              >
+                {kind === "file" ? t("browse.selectFile") : t("browse.select")}
+              </button>
+            </div>
+          </div>
         </div>
       </div>
     </div>

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/LaneChangesPanel.tsx

@@ -17,12 +17,16 @@
  *              image file is shown as the picture (`GET …/git/raw`)
  *   history  — recent commits; opening one shows that commit's diff
  *   browse   — quick-open by path, or the repo's tracked file tree (the
- *              mode switcher's Files button; at full width the sidebar)
+ *              mode switcher's Files button; at full width the sidebar);
+ *              a row dragged onto a prompt box attaches it as `@path`
  *
  * and three ranges: `work` (uncommitted, what the agent has touched right
  * now), `branch` (`base...HEAD`, what this lane adds on top of its base) and
  * `commit` (one commit, reached from history).
  *
+ * A file can also be opened from outside the panel (`openRequest`: a chat's
+ * "Edited N files" card), the same way a click in the tree opens it.
+ *
  * Only the overview polls. Review, file, history and browse are a deliberate
  * read of a frozen moment — re-fetching under the reader's scroll position is
  * worse than a slightly stale view, and those are the expensive shapes.
@@ -83,6 +87,7 @@ import {
   ChevronsDownUp,
   ChevronsUpDown,
   Check,
+  Download,
   Code2,
   Columns2,
   Eye,
@@ -99,6 +104,7 @@ import {
   UnfoldVertical,
 } from "lucide-react";
 import { api, gitTarget } from "../../lib/api";
+import { usePermissions } from "../AuthGate";
 import { pasteToLane } from "../../lib/panePaste";
 import { confirmDialog, confirmDiscard as askDiscard } from "../../lib/confirm";
 import { copyText } from "../../lib/clipboard";
@@ -117,10 +123,12 @@ import {
   type LaneDiffChange,
 } from "./LaneDiffView";
 import { LaneConflictView } from "./LaneConflictView";
+import { FileExplorer } from "./FileExplorer";
 import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "../ContextMenu";
 import { MarkdownPreview, isMarkdown } from "../MarkdownPreview";
 import { LaneGitHeader, useLaneGitFacts } from "./LaneGitHeader";
 import { changeTree, treeFiles, type ChangeTreeDir } from "../../lib/changeTree";
+import { dragProjectPath } from "../../lib/promptAttach";
 import { commitGraph, type GraphRow } from "../../lib/commitGraph";
 import type {
   LaneChangeFile,
@@ -277,6 +285,8 @@ function TreeNodes({
               data-tree-ignored={e.ignored || undefined}
               onClick={() => (e.dir ? onToggleDir(e.path) : onOpenFile(e.path))}
               onContextMenu={onMenu && ((ev) => onMenu(ev, e))}
+              draggable
+              onDragStart={(ev) => dragProjectPath(ev, e.dir ? `${e.path}/` : e.path)}
               style={{ paddingLeft: `${depth * 0.9 + 0.25}rem` }}
               aria-current={active === e.path ? "true" : undefined}
               className={`flex w-full items-center gap-1 rounded px-1 py-0.5 text-left font-mono text-[11px] hover:bg-surface-2 ${
@@ -636,6 +646,8 @@ function ChangeRow({
       <button
         type="button"
         onClick={() => onOpen(f.path)}
+        draggable
+        onDragStart={(ev) => dragProjectPath(ev, f.path)}
         className="flex min-w-0 flex-1 items-baseline gap-1.5 rounded px-1 py-0.5 text-left hover:bg-surface-2"
       >
         <span
@@ -792,18 +804,29 @@ function GraphCell({ row, width }: { row: GraphRow; width: number }) {
 export function LaneChangesPanel({
   laneId,
   session,
+  source,
   onNewLane,
   full = false,
   wide = full,
   onDirtyChange,
+  openRequest = null,
+  filesChanged = 0,
 }: {
   laneId: number;
+  /** Bumped when files changed outside this panel (the header's File
+   *  Explorer): the tree is read again, its open folders kept open. */
+  filesChanged?: number;
+  /** Open this file (relative to the panel's folder); a new `nonce` asks again. */
+  openRequest?: { path: string; nonce: number } | null;
   /** The whole-file editor holds unsaved text (true) or not (false). */
   onDirtyChange?: (dirty: boolean) => void;
   /** Show and act on that session's own worktree (`claude --worktree`)
    *  instead of the workspace's folder. The Workspace keys the panel on it,
    *  so a different session is a fresh panel. */
   session?: string;
+  /** Show and act on that extra folder's repo instead (`lane_sources` id);
+   *  wins over `session`, and is keyed on like it. */
+  source?: number;
   /** Open the Add-lane flow for a sibling worktree; see `LaneGitBar`. */
   onNewLane?: (branch?: string) => void;
   /** The panel has the whole width: the file tree becomes a sidebar and a
@@ -815,11 +838,11 @@ export function LaneChangesPanel({
   const { t } = useTranslation(["lanes"]);
   // One read of the working copy, shared by the header and every write below:
   // a stage, a discard or a commit changes the counts the header shows.
-  const [git, refreshGit] = useLaneGitFacts(laneId, session);
+  const [git, refreshGit] = useLaneGitFacts(laneId, session, source);
   // A merge, cherry-pick or revert is open: no new one starts from history.
   const opOpen = !!(git?.available && git.merging);
   // Every git read and write below goes to the same tree as those facts.
-  const target = gitTarget(laneId, session);
+  const target = gitTarget(laneId, session, source);
   // A diff line's comment goes into this workspace's pane, as a paste.
   const comment = useCallback(
     (text: string) => {
@@ -836,6 +859,9 @@ export function LaneChangesPanel({
   // history and the tree too, not just the diff `load` re-reads.
   const [reread, setReread] = useState(0);
   const [range, setRange] = useState<LaneChangeRange>("work");
+  // Local mode: the files are already on this machine — no upload, download
+  // or File Explorer (the desktop's file manager does all three).
+  const { local } = usePermissions();
   const [mode, setMode] = useState<Mode>("overview");
   const [openFile, setOpenFile] = useState<string | null>(null);
   // An image opens as a picture, never as text or a binary diff.
@@ -851,6 +877,16 @@ export function LaneChangesPanel({
   const [mdPreview, setMdPreview] = useState(false);
   useEffect(() => setMdPreview(false), [openFile]);
   const [data, setData] = useState<LaneChanges | null>(null);
+  // A folder that is not a repo (an empty new workspace, a parent of clones)
+  // has no changes, review or history — only its files, which Files reads
+  // from the disk. Open there instead of on a page that only says "no git".
+  // Both reads must say so: the facts alone also read "unavailable" on a
+  // network error or an older server.
+  const notRepo = git?.available === false && data?.available === false;
+  useEffect(() => {
+    if (notRepo && (mode === "overview" || mode === "review" || mode === "history"))
+      setMode(full ? "overview" : "browse");
+  }, [notRepo, mode, full]);
   const [commits, setCommits] = useState<LaneCommit[] | null>(null);
   // A folder's children, keyed by its path ("" is the root) — fetched once,
   // on first expand, and kept so re-collapsing doesn't re-fetch.
@@ -923,6 +959,13 @@ export function LaneChangesPanel({
   const [message, setMessage] = useState("");
   // The commit row amends the last commit instead of making a new one.
   const [amend, setAmend] = useState(false);
+  // The last commit is already on its upstream: the server refuses to amend
+  // it (EPUSHED), so the box is not offered — asking first and failing after
+  // the confirm only costs the user a click.
+  const headPushed = !!git?.available && !!git.upstream && git.ahead === 0 && !!git.head;
+  useEffect(() => {
+    if (headPushed) setAmend(false);
+  }, [headPushed]);
   // The files the commit takes (JetBrains' checkboxes). A path listed for the
   // first time arrives with its default; `seenPaths` is the last full list,
   // so a poll never re-ticks a file the user unticked.
@@ -1052,19 +1095,32 @@ export function LaneChangesPanel({
   }, [mode, laneId, query, reread, full, treeRootLoaded]);
 
   // A folder's children are fetched lazily, the first time it is expanded.
+  const readDir = (path: string) =>
+    api.lanes
+      .gitTree(target, path)
+      .then(forLane(laneId, (r) => setTreeChildren((prev) => ({ ...prev, [path]: r.entries }))))
+      .catch((err) => setError(err instanceof Error ? err.message : String(err)));
   const toggleDir = (path: string) => {
+    const opening = !expandedDirs.has(path);
     setExpandedDirs((prev) => {
       const next = new Set(prev);
       if (!next.delete(path)) next.add(path);
       return next;
     });
-    if (path in treeChildren) return;
-    void api.lanes
-      .gitTree(target, path)
-      .then(forLane(laneId, (r) => setTreeChildren((prev) => ({ ...prev, [path]: r.entries }))))
-      .catch((err) => setError(err instanceof Error ? err.message : String(err)));
+    // Every OPEN reads the folder again (the cached level shows meanwhile):
+    // files land in it from outside the panel — an agent, the terminal, the
+    // File Explorer — and a level cached while it was empty stayed empty.
+    if (opening) void readDir(path);
   };
 
+  // Files changed outside the panel: read the root and every open folder again.
+  useEffect(() => {
+    if (!filesChanged) return;
+    void readDir("");
+    for (const p of expandedDirs) void readDir(p);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filesChanged]);
+
   const [treeBusy, setTreeBusy] = useState(false);
 
   // "Expand all" is ONE read of the whole tree: a request per folder meant a
@@ -1232,6 +1288,11 @@ export function LaneChangesPanel({
   const show = (path: string) => {
     void confirmDrop().then((ok) => ok && showNow(path));
   };
+  // A file named from outside the panel (a chat's "Edited N files" card).
+  useEffect(() => {
+    if (openRequest) show(openRequest.path);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- once per request
+  }, [openRequest?.nonce]);
   // A file's history (Show History): the commits that touched it.
   const showHistory = (path: string) => {
     void confirmDrop().then((ok) => {
@@ -1593,8 +1654,32 @@ export function LaneChangesPanel({
               <MenuItem onSelect={pick(treeCtx.close, () => showHistory(treeCtx.menu!.item.path))}>
                 {t("changes.showHistory")}
               </MenuItem>
+              {!local && (
+                <MenuItem
+                  testId="lane-changes-menu-download"
+                  onSelect={pick(treeCtx.close, () => download(treeCtx.menu!.item.path))}
+                >
+                  {t("changes.download")}
+                </MenuItem>
+              )}
             </>
           )}
+          {!local && treeCtx.menu.item.dir && (
+            <MenuItem
+              testId="lane-changes-menu-upload"
+              onSelect={pick(treeCtx.close, () => pickUpload(treeCtx.menu!.item.path))}
+            >
+              {t("changes.uploadHere")}
+            </MenuItem>
+          )}
+          {!local && treeCtx.menu.item.dir && (
+            <MenuItem
+              testId="lane-changes-menu-explorer"
+              onSelect={pick(treeCtx.close, () => setExplorer({ path: treeCtx.menu!.item.path }))}
+            >
+              {t("changes.openInExplorer")}
+            </MenuItem>
+          )}
           <MenuItem onSelect={pick(treeCtx.close, () => copy(treeCtx.menu!.item.path))}>
             {t("changes.copyPath")}
           </MenuItem>
@@ -1840,6 +1925,61 @@ export function LaneChangesPanel({
   };
   const [rereading, runReread] = useSpin(rereadAll);
 
+  // Files tab transfers (issue #78): a download is a plain attachment link; an
+  // upload only creates, into the folder it was asked for ("" = the root).
+  const uploadInput = useRef<HTMLInputElement>(null);
+  const uploadDir = useRef("");
+  const [, setUploading] = useState(false);
+  // The File Explorer (the toolbar button where Upload was); the tree is
+  // re-read when it closes after changing anything.
+  const [explorer, setExplorer] = useState<{ path: string } | null>(null);
+  const explorerChanged = useRef(false);
+  const download = (path: string) => {
+    const a = document.createElement("a");
+    a.href = api.lanes.gitDownloadUrl(target, path);
+    a.download = path.split("/").pop() || path;
+    a.click();
+  };
+  const pickUpload = (dir: string) => {
+    uploadDir.current = dir;
+    uploadInput.current?.click();
+  };
+  const upload = async (files: File[]) => {
+    if (!files.length) return;
+    const lane = laneId;
+    const dir = uploadDir.current;
+    setUploading(true);
+    let saved = 0;
+    try {
+      for (const f of files) {
+        try {
+          await api.lanes.gitUpload(target, dir, f);
+          saved++;
+        } catch (err) {
+          toast.error(
+            t("changes.uploadFailed", {
+              name: f.name,
+              message: err instanceof Error ? err.message : String(err),
+            })
+          );
+        }
+      }
+    } finally {
+      if (laneNow.current === lane) {
+        setUploading(false);
+        if (saved) {
+          toast.success(t("changes.uploaded", { count: saved, dir: dir || "/" }));
+          // Re-read the level it landed in, and open it.
+          void api.lanes
+            .gitTree(target, dir)
+            .then(forLane(lane, (r) => setTreeChildren((prev) => ({ ...prev, [dir]: r.entries }))))
+            .catch(() => undefined);
+          if (dir) setExpandedDirs((prev) => new Set(prev).add(dir));
+        }
+      }
+    }
+  };
+
   const toggleCollapsed = (path: string) =>
     setCollapsed((prev) => {
       const next = new Set(prev);
@@ -2026,6 +2166,36 @@ export function LaneChangesPanel({
           aria-label={t("changes.quickOpen")}
           className="w-full rounded border border-border bg-surface-1 px-2 py-1 font-mono text-[11px] text-fg-primary"
         />
+        {/* The File Explorer's button lives in the panel header now (beside
+            Full screen); this instance serves the tree's "Open in File
+            Explorer". */}
+        <FileExplorer
+          open={!!explorer}
+          laneId={laneId}
+          session={session}
+          source={source}
+          initialPath={explorer?.path ?? ""}
+          onChanged={() => (explorerChanged.current = true)}
+          onClose={() => {
+            setExplorer(null);
+            if (explorerChanged.current) {
+              explorerChanged.current = false;
+              void rereadAll();
+            }
+          }}
+        />
+        <input
+          ref={uploadInput}
+          type="file"
+          multiple
+          hidden
+          data-testid="lane-changes-upload-input"
+          onChange={(e) => {
+            const files = [...(e.target.files ?? [])];
+            e.target.value = "";
+            void upload(files);
+          }}
+        />
         {!hits && (
           <IconButton
             label={
@@ -2053,6 +2223,8 @@ export function LaneChangesPanel({
               <button
                 type="button"
                 onClick={() => void openWhole(p)}
+                draggable
+                onDragStart={(ev) => dragProjectPath(ev, p)}
                 className="w-full truncate rounded px-1 py-0.5 text-left font-mono text-[11px] text-fg-primary hover:bg-surface-2"
               >
                 {p}
@@ -2105,6 +2277,7 @@ export function LaneChangesPanel({
         <LaneGitHeader
           laneId={laneId}
           session={session}
+          source={source}
           git={git}
           onChanged={rereadAll}
           onNewLane={onNewLane}
@@ -2124,14 +2297,16 @@ export function LaneChangesPanel({
                 <ChevronLeft className="h-3 w-3" />
                 {t("changes.back")}
               </button>
-            ) : (
+            ) : notRepo && full ? null : (
               <div className="flex min-w-0 items-center rounded border border-border bg-surface-2 p-0.5">
                 {/* Files is the whole repo's tree; at full width it is the
                   sidebar already, so no button. */}
-                {(full
-                  ? (["overview", "review", "history"] as const)
-                  : (["overview", "browse", "review", "history"] as const)
-                ).map((m) => (
+                {(notRepo
+                  ? (["browse"] as const)
+                  : full
+                    ? (["overview", "review", "history"] as const)
+                    : (["overview", "browse", "review", "history"] as const)
+                ).map((m: Mode) => (
                   <button
                     key={m}
                     type="button"
@@ -2486,8 +2661,12 @@ export function LaneChangesPanel({
             browsePane
           ) : !data ? (
             <p className="text-[11px] text-fg-muted">{t("changes.loading")}</p>
-          ) : !data.available ? (
-            <p className="text-[11px] text-fg-muted">{t("changes.unavailable")}</p>
+          ) : !data.available && mode !== "file" ? (
+            // A file still opens from Files: its whole-file read is the disk's,
+            // not git's.
+            <p className="text-[11px] text-fg-muted">
+              {t(source ? "changes.unavailableFolder" : "changes.unavailable")}
+            </p>
           ) : files.length === 0 && mode !== "file" ? (
             <p className="text-[11px] text-fg-muted">{t(`changes.empty.${range}`)}</p>
           ) : mode === "overview" ? (
@@ -2540,13 +2719,16 @@ export function LaneChangesPanel({
                   </div>
                   <div className="flex flex-wrap items-center gap-1.5">
                     <label
-                      title={t("changes.amendHint")}
-                      className="flex shrink-0 cursor-pointer items-center gap-1 text-[11px] text-fg-secondary"
+                      title={headPushed ? t("changes.amendPushed") : t("changes.amendHint")}
+                      className={`flex shrink-0 items-center gap-1 text-[11px] text-fg-secondary ${
+                        headPushed ? "cursor-not-allowed opacity-50" : "cursor-pointer"
+                      }`}
                     >
                       <input
                         type="checkbox"
                         data-testid="lane-changes-amend"
                         checked={amend}
+                        disabled={headPushed}
                         onChange={(e) => setAmend(e.target.checked)}
                       />
                       {t("changes.amend")}
@@ -2678,6 +2860,7 @@ export function LaneChangesPanel({
             <LaneConflictView
               laneId={laneId}
               session={session}
+              source={source}
               path={openFile}
               onResolved={() => {
                 refreshGit();
@@ -2731,6 +2914,18 @@ export function LaneChangesPanel({
                       {mdPreview ? t("changes.raw") : t("changes.preview")}
                     </button>
                   )}
+                  {!local && range !== "commit" && openFile && (
+                    <button
+                      type="button"
+                      data-testid="lane-file-download"
+                      onClick={() => download(openFile)}
+                      title={t("changes.download")}
+                      className="flex shrink-0 items-center gap-1 self-center rounded border border-border-light px-1.5 py-0.5 text-[11px] text-fg-secondary hover:bg-surface-2 hover:text-fg-primary"
+                    >
+                      <Download className="h-3 w-3" />
+                      {t("changes.download")}
+                    </button>
+                  )}
                   {/* Only the working file is editable: a commit is history. */}
                   {/* A working file opens in the editor; the read-only diff
                       (Whole file off) keeps an Edit button back into it. */}
@@ -2811,7 +3006,9 @@ export function LaneChangesPanel({
                         collapse={!whole}
                         revertLabel={t("changes.revertBlock")}
                         value={draft}
-                        original={baseText ?? draft}
+                        // Outside a repo there is no HEAD: the edits are
+                        // shown against the text as it was opened.
+                        original={(notRepo ? text?.lines.join("\n") : baseText) ?? draft}
                         lang={langFor(openFile ?? "")}
                         label={t("changes.editorLabel", { path: openFile })}
                         onChange={setDraft}

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/LaneGitBar.tsx

@@ -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 || []);
@@ -246,13 +242,27 @@ export function LaneGitBar({
       void run(action, body);
     }
   };
-  const push = () =>
-    confirmRun(
+  const push = async () => {
+    let ahead = git.ahead ?? 0;
+    if (git.upstream && ahead === 0) {
+      // The facts can be up to 30 s old (an agent may have just committed):
+      // ask git again before saying there is nothing to push — and never
+      // ask to confirm pushing zero commits.
+      const read = await api.lanes.git(gitTarget(laneId, session, source)).catch(() => null);
+      const fresh = read?.available ? read : null;
+      ahead = fresh?.ahead ?? 0;
+      if (fresh?.upstream && ahead === 0) {
+        toast.info(t("gitBar.nothingToPush", { upstream: fresh.upstream }));
+        onChanged();
+        return;
+      }
+    }
+    return confirmRun(
       git.upstream
         ? {
             title: t("gitBar.push"),
             message: t("gitBar.pushConfirm", {
-              count: git.ahead ?? 0,
+              count: ahead,
               branch: git.branch,
               upstream: git.upstream,
             }),
@@ -263,6 +273,7 @@ export function LaneGitBar({
           },
       "push"
     );
+  };
   const publish = () =>
     confirmRun(
       {

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));
         })
@@ -73,7 +75,7 @@ export function useLaneGitFacts(
       alive = false;
       clearInterval(timer);
     };
-  }, [laneId, session, nonce]);
+  }, [laneId, session, source, nonce]);
 
   return [facts, () => setNonce((n) => n + 1)];
 }
@@ -322,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,
@@ -343,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;
@@ -374,6 +381,7 @@ export function LaneGitHeader({
       <LaneGitBar
         laneId={laneId}
         session={session}
+        source={source}
         git={git}
         onChanged={onChanged}
         onNewLane={onNewLane}

client/src/components/lanes/SessionMenu.tsx

@@ -4,20 +4,21 @@
  * the sidebar's **New session** row). Every item is something the row already
  * does: open it the way its click does (a live pane attaches, an ended session
  * opens its conversation — never a resume), open a live one in a split,
- * rename / archive / unarchive when the list offers them, copy its id, open
- * its analysis page, and close its live tab (`DELETE /api/run/:id`, what the
- * tab's X does — after the same confirm for an AI tab, which may be mid-turn).
+ * rename / pin / unpin / archive / unarchive when the list offers them, copy its id, open
+ * its analysis page, and end its live tab as the tab's buttons do (`endRuns`,
+ * after the same confirm for an AI tab, which may be mid-turn): **Sleep** stops
+ * it and keeps the session listed to resume later, **Close tab** stops it and
+ * archives the session.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
 import { useTranslation } from "react-i18next";
 import { useNavigate } from "react-router-dom";
-import { api, type RunHandle } from "../../lib/api";
+import type { RunHandle } from "../../lib/api";
 import type { Session } from "../../lib/types";
 import { ContextMenu, MenuItem, MenuSeparator, type MenuPoint } from "../ContextMenu";
-import { confirmDialog } from "../../lib/confirm";
 import { copyText } from "../../lib/clipboard";
-import { toast } from "../../lib/toast";
+import { canSleep, endRuns } from "../../lib/stopSession";
 
 export function SessionMenu({
   laneId,
@@ -29,6 +30,7 @@ export function SessionMenu({
   onRename,
   onArchive,
   onUnarchive,
+  onPin,
 }: MenuPoint & {
   laneId: number;
   session: Session | null;
@@ -38,6 +40,8 @@ export function SessionMenu({
   onRename?: () => void;
   onArchive?: () => void;
   onUnarchive?: () => void;
+  /** Pin or unpin (by `session.pinned_at`), where the list offers it. */
+  onPin?: () => void;
 }) {
   const { t } = useTranslation("lanes");
   const navigate = useNavigate();
@@ -47,24 +51,12 @@ export function SessionMenu({
     onClose();
     fn();
   };
-  const closeTab = async () => {
+  // Stop archives the session; Sleep keeps it listed to resume later
+  // (`endRuns` asks first for an AI pane, which may be mid-turn).
+  const endTab = (sleep: boolean) => {
     if (!run) return;
     onClose();
-    if (
-      run.tool !== "shell" &&
-      !(await confirmDialog({
-        title: t("tabs.stopTitle", { name: session?.name || t("tree.newSession") }),
-        message: t("tabs.stopBody"),
-        confirmLabel: t("tabs.stopConfirm"),
-        destructive: true,
-      }))
-    )
-      return;
-    try {
-      await api.run.kill(run.id);
-    } catch (err) {
-      toast.error(err);
-    }
+    void endRuns([run], { sleep, name: session?.name || t("tree.newSession"), t });
   };
 
   return (
@@ -84,6 +76,11 @@ export function SessionMenu({
         </MenuItem>
       )}
       {onRename && <MenuItem onSelect={pick(onRename)}>{t("menu.rename")}</MenuItem>}
+      {onPin && session && (
+        <MenuItem onSelect={pick(onPin)}>
+          {t(session.pinned_at ? "sessionMenu.unpin" : "sessionMenu.pin")}
+        </MenuItem>
+      )}
       {session && (
         <>
           <MenuItem onSelect={pick(() => navigate(`/sessions/${session.id}`))}>
@@ -97,8 +94,13 @@ export function SessionMenu({
       {(run || onArchive || onUnarchive) && <MenuSeparator />}
       {onUnarchive && <MenuItem onSelect={pick(onUnarchive)}>{t("tree.unarchive")}</MenuItem>}
       {onArchive && <MenuItem onSelect={pick(onArchive)}>{t("sessionMenu.archive")}</MenuItem>}
+      {canSleep(run) && (
+        <MenuItem testId="session-menu-sleep" onSelect={() => endTab(true)}>
+          {t("tabs.sleep")}
+        </MenuItem>
+      )}
       {run && (
-        <MenuItem danger onSelect={() => void closeTab()}>
+        <MenuItem danger onSelect={() => endTab(false)}>
           {t("tabs.close")}
         </MenuItem>
       )}

client/src/components/lanes/SessionReplay.tsx

@@ -121,14 +121,22 @@ 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} fill />
+        <ConversationView
+          sessionId={sessionId}
+          fill
+          ended={!livePane && !!session && session.status !== "active"}
+        />
       </div>
       {livePane ? (
         <div
@@ -173,6 +181,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/WorkspaceContext.tsx

@@ -0,0 +1,571 @@
+/**
+ * @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; the
+ * same form clones related repos beside the workspace (`CloneSourcesForm`).
+ * @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";
+import { CloneSourcesForm } from "./CloneSourcesForm";
+
+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>
+          )}
+          {folderOpen && (
+            <CloneSourcesForm
+              laneId={lane.id}
+              parent={lane.cwd.replace(/\/+$/, "").replace(/\/[^/]*$/, "") || "/"}
+              onAdded={(next) => {
+                setView(next);
+                onSourcesChange?.(next);
+              }}
+            />
+          )}
+        </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,7 +5,8 @@
  * 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
+ * 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
@@ -15,40 +16,30 @@
  * **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,
   SquareTerminal,
-  X,
 } from "lucide-react";
 import {
   api,
   type CodexApproval,
   type CodexSandbox,
   type EffortLevel,
-  type LaneMemoryFile,
-  type LaneSource,
   type LaneSourcesView,
   type ModelChoice,
   type PermissionMode,
@@ -57,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 { 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,
@@ -84,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;
@@ -114,17 +99,23 @@ 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);
@@ -148,6 +139,7 @@ function HomeBody({
     }
   }, [draftKey, prompt]);
   const [images, setImages] = useState<PromptImage[]>([]);
+  const pickFiles = useRef<(() => void) | null>(null);
   const [proxy, setProxy] = useSessionProxy();
   const proxies = useAiProxies();
   // Claude and Codex, also before the catalog has loaded (as ProxyPicker).
@@ -173,7 +165,8 @@ function HomeBody({
   // 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.
@@ -196,27 +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 [ctxDrag, setCtxDrag] = useState(false);
-  const addFiles = async (picked: File[]) => {
-    for (const f of picked) {
-      if (!(await run(() => api.lanes.addFile(lane.id, f)))) break;
-    }
-  };
-  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}`;
@@ -245,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);
@@ -280,42 +236,6 @@ 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>) => {
-    setError(null);
-    try {
-      setView(await fn());
-      return true;
-    } catch (err) {
-      setError(message(err));
-      return false;
-    }
-  };
-
   // 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 () => {
@@ -357,6 +277,13 @@ function HomeBody({
         ...(claude && inWorktree && project?.root ? { worktree: true } : {}),
       });
       setPrompt("");
+      // Here, not only through the effect: the navigate below unmounts this
+      // home in the same batch, so the effect never sees the empty prompt.
+      try {
+        localStorage.removeItem(draftKey);
+      } catch {
+        /* storage unavailable: nothing was kept */
+      }
       images.forEach((i) => i.url && URL.revokeObjectURL(i.url));
       setImages([]);
       navigate(`/workspace?lane=${lane.id}&run=${encodeURIComponent(runId)}`);
@@ -438,10 +365,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";
 
@@ -450,7 +374,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>
@@ -529,12 +453,22 @@ 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"
@@ -800,363 +734,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
-          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="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={(e) => {
-                const picked = [...(e.target.files ?? [])];
-                e.target.value = "";
-                void addFiles(picked);
-              }}
-            />
-          </div>
-          <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 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
@@ -1174,34 +756,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,12 +1,13 @@
 /**
  * @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, the ones with a live
- * pane above the ended ones) — never the other
+ * (`GET /api/sessions?lane=<id>&archived=0&pinned_first=1`, newest first —
+ * pinned ones on top in pin order, then the ones with a live pane, then the
+ * ended ones; a pin is `PATCH {pinned}`, issue #80) — 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
- * renames it and its hover button archives it (`PATCH {name}` / `{archived}`,
+ * renames it, its hover buttons pin/unpin and archive it (`PATCH {name}` / `{archived}`,
  * which deletes nothing); a right-click opens the same actions and more
  * (`SessionMenu`). A session with a LIVE pane (a `GET /api/run` handle
  * carrying its session id) opens that tmux pane on the Workspace page
@@ -24,14 +25,16 @@
  * 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 } from "lucide-react";
+import { Archive, GitBranch, Pin, PinOff, SquareTerminal } from "lucide-react";
 import { useTranslation } from "react-i18next";
 import { Link, useNavigate } from "react-router-dom";
 import { api, type RunHandle } from "../../lib/api";
@@ -220,6 +223,7 @@ export function WorkspaceSessionList({
   selectedSessionId = null,
   onMatches,
   hidden = false,
+  readOnly = false,
 }: {
   lane: Lane;
   /** Every live dashboard pane, from `GET /api/run`. */
@@ -235,6 +239,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();
@@ -273,17 +279,21 @@ export function WorkspaceSessionList({
     3000
   );
   const refreshKey = `${hookKey}:${version}`;
-  const own = useSessionPage({ lane: lane.id, archived: false, limit }, refreshKey);
+  const own = useSessionPage(
+    { lane: lane.id, archived: false, pinnedFirst: true, 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 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).
+  // Pinned sessions first, then live ones, then ended ones — each group in
+  // the server's order (pin order, else newest first; the sort is stable).
+  const rank = (s: Session) => (s.pinned_at ? 0 : runFor(s) ? 1 : 2);
   const shown = (sessions ?? [])
     .filter((s) => !q || (s.name ?? "").toLowerCase().includes(q) || s.id.startsWith(q))
-    .sort((a, b) => Number(!!runFor(b)) - Number(!!runFor(a)));
+    .sort((a, b) => rank(a) - rank(b));
   // 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.
@@ -315,7 +325,7 @@ export function WorkspaceSessionList({
     };
   }, [orphanIds]);
   const fresh =
-    sessions === null || q
+    sessions === null || q || readOnly
       ? []
       : [
           ...laneRuns.filter(
@@ -331,7 +341,10 @@ export function WorkspaceSessionList({
     if (count !== null) onMatches?.(count);
   }, [count, onMatches]);
 
-  const patch = async (s: Session, body: { name?: string; archived?: boolean }) => {
+  const patch = async (
+    s: Session,
+    body: { name?: string; archived?: boolean; pinned?: boolean }
+  ) => {
     setError(null);
     try {
       await api.sessions.patch(s.id, body);
@@ -492,6 +505,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)}`
@@ -501,19 +515,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"
@@ -527,6 +541,13 @@ export function WorkspaceSessionList({
                 />
                 <span className="sr-only">{t(`tree.state.${sessionDotLabel(s, !!run)}`)}</span>
                 <span className="truncate">{s.name || s.id.slice(0, 8)}</span>
+                {s.pinned_at && (
+                  <Pin
+                    data-testid={`workspace-session-pinned-${s.id}`}
+                    aria-label={t("tree.pinned")}
+                    className="h-3 w-3 shrink-0 text-fg-muted"
+                  />
+                )}
                 {sessionWorktreeName(lane, s) && (
                   <GitBranch
                     data-testid={`workspace-session-worktree-${s.id}`}
@@ -534,26 +555,46 @@ export function WorkspaceSessionList({
                     className="h-3 w-3 shrink-0 text-fg-muted"
                   />
                 )}
-                <span className="ml-auto shrink-0 text-[11px] tabular-nums text-fg-muted">
+                <span
+                  className={`ml-auto shrink-0 text-[11px] tabular-nums text-fg-muted ${readOnly ? "" : "group-hover:invisible"}`}
+                >
                   {timeAgo(s.last_activity ?? s.started_at, true)}
                 </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-pin-${s.id}`}
+                  onClick={() => void patch(s, { pinned: !s.pinned_at })}
+                  title={t(s.pinned_at ? "tree.unpinSession" : "tree.pinSession")}
+                  aria-label={t(s.pinned_at ? "tree.unpinSession" : "tree.pinSession")}
+                  className="absolute right-6 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"
+                >
+                  {s.pinned_at ? (
+                    <PinOff className="h-3.5 w-3.5" />
+                  ) : (
+                    <Pin 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>
           );
         })}
@@ -600,6 +641,9 @@ export function WorkspaceSessionList({
           onClose={sessionCtx.close}
           onRename={() => startRename(sessionCtx.menu!.item)}
           onArchive={() => void archive(sessionCtx.menu!.item)}
+          onPin={() =>
+            void patch(sessionCtx.menu!.item, { pinned: !sessionCtx.menu!.item.pinned_at })
+          }
         />
       )}
     </>

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

@@ -25,8 +25,11 @@ vi.mock("../../../lib/api", () => ({
       pipelines: vi.fn(),
       worktree: vi.fn(),
       ensure: vi.fn(),
+      clone: vi.fn(),
       browse: vi.fn(),
       pickPath: vi.fn(),
+      // The folder browser's Places list the user's workspaces.
+      list: vi.fn(() => Promise.resolve({ lanes: [], counts: {} })),
       get: vi.fn(),
       profileInit: vi.fn(),
       mcpSync: vi.fn(),
@@ -154,6 +157,7 @@ beforeEach(() => {
   vi.mocked(api.lanes.branches).mockReset();
   vi.mocked(api.lanes.worktree).mockReset();
   vi.mocked(api.lanes.ensure).mockReset();
+  vi.mocked(api.lanes.clone).mockReset();
   vi.mocked(api.lanes.browse).mockReset();
   vi.mocked(api.lanes.pickPath).mockReset();
   // Provisioning finishes instantly by default - tests that care about the
@@ -582,6 +586,17 @@ describe("AddLaneModal — folder browse", () => {
     expect(api.lanes.browse).not.toHaveBeenCalled();
   });
 
+  it("a click into the path field only focuses it — no picker opens (#77)", async () => {
+    renderModal();
+    const user = userEvent.setup();
+    const field = document.getElementById("add-lane-repo")!;
+
+    await user.click(field);
+    expect(field).toHaveFocus();
+    expect(api.lanes.pickPath).not.toHaveBeenCalled();
+    expect(api.lanes.browse).not.toHaveBeenCalled();
+  });
+
   it("falls back to the in-app browser when no native picker is available", async () => {
     noNativePicker();
     vi.mocked(api.lanes.browse).mockResolvedValue({
@@ -601,7 +616,7 @@ describe("AddLaneModal — folder browse", () => {
     expect(onClose).not.toHaveBeenCalled();
   });
 
-  it("opens the browser, lists subdirectories, and selecting one fills the path field", async () => {
+  it("opens the browser, lists subdirectories, and a double-click opens one", async () => {
     noNativePicker();
     vi.mocked(api.lanes.browse).mockResolvedValue({
       path: "/Users/tester",
@@ -614,8 +629,8 @@ describe("AddLaneModal — folder browse", () => {
     await user.click(screen.getByTitle("Browse for a folder"));
     expect(await screen.findByText("projects")).toBeInTheDocument();
 
-    await user.click(screen.getByText("projects"));
-    expect(api.lanes.browse).toHaveBeenCalledWith("/Users/tester/projects");
+    await user.dblClick(screen.getByText("projects"));
+    expect(api.lanes.browse).toHaveBeenCalledWith("/Users/tester/projects", false, false, false);
   });
 
   it("Escape closes only the folder browser, not the whole modal", async () => {
@@ -655,46 +670,18 @@ describe("AddLaneModal — create/update readme", () => {
 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/ });
+    await waitFor(() => expect(api.aiTools.list).toHaveBeenCalled());
     expect(screen.queryByRole("radio", { name: "AI Proxy" })).toBeNull();
     expect(api.aiProxies.list).not.toHaveBeenCalled();
   });
 });
 
 describe("AddLaneModal — tool selection", () => {
-  it("sends the picked tool when adopting a repo", async () => {
-    vi.mocked(api.lanes.ensure).mockResolvedValue({
-      lane: laneFixture({ id: 23, kind: "adopted", status: "idle" }),
-      created: true,
-    });
-    const onAdded = vi.fn();
-    const onClose = vi.fn();
-    renderModal({ onAdded, onClose });
-    const user = userEvent.setup();
-
-    await user.click(screen.getByRole("button", { name: "Repo" }));
-    const dirField = screen.getByLabelText("Directory");
-    await focusField(user, dirField);
-    await user.type(dirField, "/tmp/demo");
-    // One button showing the default; it opens every installed + enabled tool.
-    const picker = await screen.findByRole("button", { name: /Claude Code.*Default/ });
-    expect(picker).toHaveAttribute("aria-expanded", "false");
-    await user.click(picker);
-    const list = screen.getByRole("group", { name: /Which CLI drives this workspace/ });
-    expect(
-      within(list)
-        .getAllByRole("button")
-        .map((b) => b.textContent)
-    ).toEqual(["Claude Code", "Codex", "Gemini"]);
-    await user.click(within(list).getByRole("button", { name: "Codex" }));
-    // The picked tool replaces the default on the button, and the list closes.
-    expect(screen.getByRole("button", { name: "Codex", expanded: false })).toBeInTheDocument();
-    expect(screen.queryByRole("button", { name: "Gemini" })).toBeNull();
-    await user.click(screen.getByRole("button", { name: /add workspace|create/i }));
-
-    await waitFor(() =>
-      expect(api.lanes.ensure).toHaveBeenCalledWith(expect.objectContaining({ tool: "codex" }))
-    );
+  it("offers no tool picker: a new session picks its own AI", async () => {
+    renderModal({});
+    await waitFor(() => expect(api.aiTools.list).toHaveBeenCalled());
+    expect(screen.queryByRole("button", { name: /Claude Code/ })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Codex" })).toBeNull();
   });
 
   it("says so, with a link to Settings, when no tool is installed and enabled", async () => {
@@ -766,3 +753,76 @@ describe("AddLaneModal — working straight on main (no worktree)", () => {
     );
   });
 });
+
+describe("AddLaneModal — Clone", () => {
+  async function fillClone(user: ReturnType<typeof userEvent.setup>, url: string) {
+    renderModal();
+    fireEvent.click(screen.getByRole("button", { name: "Clone" }));
+    const urlField = screen.getByLabelText("Repository URL");
+    await focusField(user, urlField);
+    await user.type(urlField, url);
+    await user.type(screen.getByLabelText("Clone into folder"), "/home/an/code");
+  }
+
+  it("clones into <folder>/<repo name> and reports the new workspace", async () => {
+    const onAdded = vi.fn();
+    vi.mocked(api.lanes.clone).mockResolvedValue({
+      lane: laneFixture({ id: 5 }),
+      created: true,
+      path: "/home/an/code/repo",
+    });
+    const user = userEvent.setup();
+    renderModal({ onAdded });
+    fireEvent.click(screen.getByRole("button", { name: "Clone" }));
+    const urlField = screen.getByLabelText("Repository URL");
+    await focusField(user, urlField);
+    await user.type(urlField, "git@github.com:owner/repo.git");
+    await user.type(screen.getByLabelText("Clone into folder"), "/home/an/code");
+    expect(screen.getByText(/cloned to \/home\/an\/code\/repo/)).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Add workspace" }));
+    await waitFor(() =>
+      expect(api.lanes.clone).toHaveBeenCalledWith(
+        expect.objectContaining({ url: "git@github.com:owner/repo.git", parent: "/home/an/code" })
+      )
+    );
+    expect(vi.mocked(api.lanes.clone).mock.calls[0]?.[0].credentials).toBeUndefined();
+    await waitFor(() => expect(onAdded).toHaveBeenCalled());
+  });
+
+  it("asks for a login on ECREDENTIALS and sends it on the retry", async () => {
+    vi.mocked(api.lanes.clone)
+      .mockRejectedValueOnce(
+        Object.assign(new Error("needs a login"), {
+          code: "ECREDENTIALS",
+          auth: { protocol: "https", host: "git.example.com" },
+        })
+      )
+      .mockResolvedValueOnce({ lane: laneFixture({ id: 6 }), created: true, path: "/x" });
+    const user = userEvent.setup();
+    await fillClone(user, "https://git.example.com/o/r.git");
+    await user.click(screen.getByRole("button", { name: "Add workspace" }));
+    const login = await screen.findByTestId("add-lane-clone-login");
+    expect(screen.getByRole("alert")).toHaveTextContent("git.example.com needs a login");
+    await user.type(within(login).getByLabelText("Username"), "an");
+    await user.type(within(login).getByLabelText("Password or access token"), "tok");
+    await user.click(screen.getByRole("button", { name: "Add workspace" }));
+    await waitFor(() =>
+      expect(vi.mocked(api.lanes.clone).mock.calls[1]?.[0].credentials).toEqual({
+        username: "an",
+        password: "tok",
+        remember: true,
+      })
+    );
+  });
+
+  it("points to Settings → Git when the SSH key is refused", async () => {
+    vi.mocked(api.lanes.clone).mockRejectedValue(
+      Object.assign(new Error("refused"), { code: "ESSHAUTH" })
+    );
+    const user = userEvent.setup();
+    await fillClone(user, "git@github.com:o/r.git");
+    await user.click(screen.getByRole("button", { name: "Add workspace" }));
+    const link = await screen.findByRole("link", { name: "Open Settings → Git" });
+    expect(link).toHaveAttribute("href", "/settings/git#git-identity");
+  });
+});

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

@@ -0,0 +1,61 @@
+/**
+ * @file Tests for CloneSourcesForm: every URL in the box is cloned in turn as
+ * an extra folder, a host that wants a login opens the login row, and Retry
+ * re-runs only the failed URLs with that login.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import "../../../i18n";
+
+vi.mock("../../../lib/api", () => ({
+  api: { lanes: { cloneFolder: vi.fn() } },
+}));
+
+import { api, type LaneSourcesView } from "../../../lib/api";
+import { CloneSourcesForm } from "../CloneSourcesForm";
+
+const view = { sources: [] } as unknown as LaneSourcesView & { path: string };
+
+describe("CloneSourcesForm", () => {
+  beforeEach(() => vi.mocked(api.lanes.cloneFolder).mockReset());
+
+  it("clones each URL, asks for a login where needed, and retries only that one", async () => {
+    const user = userEvent.setup();
+    const onAdded = vi.fn();
+    vi.mocked(api.lanes.cloneFolder).mockImplementation(async (_id, body) => {
+      if (body?.url.includes("private") && !body.credentials)
+        throw Object.assign(new Error("login"), {
+          code: "ECREDENTIALS",
+          auth: { protocol: "https", host: "private.test" },
+        });
+      return view;
+    });
+    render(<CloneSourcesForm laneId={3} parent="/w" onAdded={onAdded} />);
+
+    await user.type(
+      screen.getByTestId("workspace-clone-input"),
+      "https://h/a.git\nhttps://private.test/b.git\nhttps://h/a.git"
+    );
+    await user.click(screen.getByTestId("workspace-clone-run"));
+
+    await waitFor(() => expect(api.lanes.cloneFolder).toHaveBeenCalledTimes(2));
+    expect(onAdded).toHaveBeenCalledTimes(1);
+    expect(await screen.findByText(/private\.test needs a login/)).toBeInTheDocument();
+    // Only what is left stays in the box.
+    expect(screen.getByTestId("workspace-clone-input")).toHaveValue("https://private.test/b.git");
+
+    await user.type(screen.getByLabelText("Username"), "dev");
+    await user.type(screen.getByLabelText("Password or access token"), "tok");
+    await user.click(screen.getByRole("button", { name: "Retry the failed ones" }));
+
+    await waitFor(() => expect(onAdded).toHaveBeenCalledTimes(2));
+    expect(api.lanes.cloneFolder).toHaveBeenLastCalledWith(3, {
+      url: "https://private.test/b.git",
+      credentials: { username: "dev", password: "tok", remember: true },
+    });
+    expect(screen.getByTestId("workspace-clone-input")).toHaveValue("");
+  });
+});

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

@@ -313,10 +313,10 @@ describe("DiffEditor", () => {
       expect(b).not.toBeNull();
       return b!;
     });
-    // Inline at the end of the first selected line, never a tooltip over the
-    // line above it.
-    expect(chip.closest(".cm-tooltip")).toBeNull();
-    expect(chip.closest(".cm-line")?.textContent).toMatch(/^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 } });

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

@@ -0,0 +1,434 @@
+/**
+ * @file Tests for the workspace File Explorer modal: it lists a folder and
+ * opens sub-folders, makes a folder inline, deletes into the Trash without a
+ * confirm, copies in one workspace and pastes into another (`fromLane`),
+ * asks Replace / Keep both / Skip when an upload's name is taken, refuses a
+ * batch over 500 MB before sending anything, restores from the user's own
+ * Trash, opens an admin's Trash on one folder per user (counted, an unreadable
+ * one saying why), opens each user's Trash from its folder (asking before a
+ * purge there, sending the item's store) and
+ * shows a Trash that could not be read as an error, never as empty.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { FileExplorer } from "../FileExplorer";
+import { api, type FsListing } from "../../../lib/api";
+import { toast } from "../../../lib/toast";
+import { confirmDialog } from "../../../lib/confirm";
+
+vi.mock("../../../lib/confirm", () => ({ confirmDialog: vi.fn(async () => false) }));
+
+vi.mock("../../../lib/api", () => ({
+  gitTarget: (lane: number, session?: string | null) => (session ? { lane, session } : lane),
+  isHomePlace: (p: unknown) => typeof p === "object" && p !== null && "home" in p,
+  api: {
+    lanes: {
+      list: vi.fn(),
+      gitDownloadUrl: (t: number, p: string) => `/api/lanes/${t}/git/download?path=${p}`,
+    },
+    files: {
+      homes: vi.fn(),
+      downloadUrl: (t: unknown, p: string) => `/dl/${JSON.stringify(t)}/${p}`,
+      list: vi.fn(),
+      mkdir: vi.fn(),
+      newFile: vi.fn(),
+      rename: vi.fn(),
+      move: vi.fn(),
+      copy: vi.fn(),
+      remove: vi.fn(),
+      trash: vi.fn(),
+      allTrash: vi.fn(),
+      restore: vi.fn(),
+      purge: vi.fn(),
+      upload: vi.fn(),
+      zipUrl: (t: number, ps: string[]) => `/api/lanes/${t}/fs/zip?p=${ps.join("&p=")}`,
+    },
+  },
+}));
+vi.mock("../../../lib/toast", () => ({
+  toast: { success: vi.fn(), error: vi.fn(), info: vi.fn() },
+}));
+
+const root: FsListing = {
+  path: "",
+  parent: null,
+  truncated: false,
+  entries: [
+    { name: "src", path: "src", type: "dir", size: null, mtime: 0 },
+    { name: "a.txt", path: "a.txt", type: "file", size: 12, mtime: 0 },
+  ],
+};
+const src: FsListing = {
+  path: "src",
+  parent: "",
+  truncated: false,
+  entries: [{ name: "x.js", path: "src/x.js", type: "file", size: 2, mtime: 0 }],
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.mocked(api.lanes.list).mockResolvedValue({
+    lanes: [
+      { id: 1, title: "one", cwd: "/w/one" },
+      { id: 2, title: "two", cwd: "/w/two" },
+    ],
+    counts: {},
+  } as never);
+  vi.mocked(api.files.list).mockImplementation(async (_t, p = "") => (p === "src" ? src : root));
+  vi.mocked(api.files.trash).mockResolvedValue({ items: [] });
+  vi.mocked(api.files.allTrash).mockResolvedValue({ items: [], errors: [] });
+  vi.mocked(api.files.homes).mockResolvedValue({
+    homes: [
+      { id: "me", label: "An", readOnly: false },
+      { id: "bob", label: "Bob", readOnly: true },
+    ],
+  });
+});
+
+const open = () => render(<FileExplorer open laneId={1} onClose={vi.fn()} onChanged={vi.fn()} />);
+const row = (name: string) =>
+  screen.getAllByTestId("fx-row").find((r) => r.textContent?.includes(name))!;
+
+describe("FileExplorer", () => {
+  it("hides dot files until Ctrl+H, like the Linux file manager", async () => {
+    vi.mocked(api.files.list).mockResolvedValue({
+      ...root,
+      entries: [
+        ...root.entries,
+        { name: ".env.example", path: ".env.example", type: "file", size: 1, mtime: 0 },
+      ],
+    });
+    open();
+    await screen.findByText("a.txt");
+    expect(screen.queryByText(".env.example")).toBeNull();
+    fireEvent.keyDown(screen.getByTestId("fx-list"), { key: "h", ctrlKey: true });
+    expect(await screen.findByText(".env.example")).toBeInTheDocument();
+  });
+
+  it("shows a labelled action bar for a selection, and goes Back after opening a folder", async () => {
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    await user.click(row("a.txt"));
+    const bar = screen.getByTestId("fx-actionbar");
+    expect(within(bar).getByRole("button", { name: /Download/ })).toBeInTheDocument();
+    expect(within(bar).getByRole("button", { name: /Move to Trash/ })).toBeInTheDocument();
+    fireEvent.doubleClick(row("src"));
+    await screen.findByText("x.js");
+    await user.click(screen.getByRole("button", { name: "Back" }));
+    await waitFor(() => expect(api.files.list).toHaveBeenLastCalledWith(1, ""));
+  });
+
+  it("lists a folder and opens a sub-folder on double-click", async () => {
+    open();
+    expect(await screen.findByText("a.txt")).toBeInTheDocument();
+    fireEvent.doubleClick(row("src"));
+    expect(await screen.findByText("x.js")).toBeInTheDocument();
+    expect(api.files.list).toHaveBeenLastCalledWith(1, "src");
+  });
+
+  it("makes a folder inline", async () => {
+    vi.mocked(api.files.mkdir).mockResolvedValue({ path: "docs" });
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    await user.click(screen.getByRole("button", { name: "New" }));
+    await user.click(screen.getByRole("menuitem", { name: "New folder" }));
+    const name = screen.getByLabelText("Name");
+    await user.clear(name);
+    await user.type(name, "docs{Enter}");
+    await waitFor(() => expect(api.files.mkdir).toHaveBeenCalledWith(1, "docs"));
+  });
+
+  it("deletes into the Trash without asking", async () => {
+    vi.mocked(api.files.remove).mockResolvedValue({ trashed: ["id1"] });
+    open();
+    await screen.findByText("a.txt");
+    fireEvent.click(row("a.txt"));
+    fireEvent.keyDown(screen.getByTestId("fx-list"), { key: "Delete" });
+    await waitFor(() => expect(api.files.remove).toHaveBeenCalledWith(1, ["a.txt"]));
+    expect(screen.queryByRole("alertdialog")).toBeNull();
+  });
+
+  it("copies here and pastes into another workspace", async () => {
+    vi.mocked(api.files.copy).mockResolvedValue({ copied: ["a.txt"] });
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    fireEvent.click(row("a.txt"));
+    fireEvent.keyDown(screen.getByTestId("fx-list"), { key: "c", ctrlKey: true });
+    await user.click(await screen.findByRole("button", { name: "two" }));
+    await waitFor(() => expect(api.files.list).toHaveBeenLastCalledWith(2, ""));
+    await user.click(screen.getByRole("button", { name: /Paste 1 item/ }));
+    await waitFor(() =>
+      expect(api.files.copy).toHaveBeenCalledWith(2, ["a.txt"], "", {
+        fromLane: 1,
+        conflict: "fail",
+      })
+    );
+  });
+
+  it("asks about a taken name on upload, and sends the choice", async () => {
+    vi.mocked(api.files.upload)
+      .mockRejectedValueOnce(
+        Object.assign(new Error("taken"), { code: "EEXISTS", names: ["a.txt"] })
+      )
+      .mockResolvedValueOnce({ path: "a (1).txt" });
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    const file = new File(["hi"], "a.txt");
+    await user.upload(screen.getByTestId("fx-upload-files"), file);
+    const ask = await screen.findByTestId("fx-conflict");
+    await user.click(within(ask).getByRole("button", { name: "Keep both" }));
+    await waitFor(() =>
+      expect(api.files.upload).toHaveBeenLastCalledWith(
+        1,
+        "a.txt",
+        file,
+        "keep",
+        expect.any(Function)
+      )
+    );
+  });
+
+  it("refuses a batch over 500 MB before sending anything", async () => {
+    open();
+    await screen.findByText("a.txt");
+    const big = new File(["x"], "big.bin");
+    Object.defineProperty(big, "size", { value: 600 * 1024 * 1024 });
+    fireEvent.change(screen.getByTestId("fx-upload-files"), { target: { files: [big] } });
+    await waitFor(() => expect(toast.error).toHaveBeenCalled());
+    expect(api.files.upload).not.toHaveBeenCalled();
+  });
+
+  it("restores from the Trash", async () => {
+    vi.mocked(api.files.trash).mockResolvedValue({
+      items: [
+        {
+          id: "abc12345",
+          name: "a.txt",
+          laneId: 1,
+          path: "a.txt",
+          isDir: false,
+          deletedAt: "2026-10-14T00:00:00Z",
+        },
+      ],
+    });
+    vi.mocked(api.files.restore).mockResolvedValue({ path: "a.txt", laneId: null });
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    await user.click(
+      within(screen.getByTestId("fx-trashes")).getByRole("button", { name: "Trash" })
+    );
+    await user.click(await screen.findByRole("button", { name: /My Trash/ }));
+    await waitFor(() => expect(api.files.trash).toHaveBeenLastCalledWith({ home: "me" }));
+    const trashRow = await screen.findByTestId("fx-trash-row");
+    await user.click(within(trashRow).getByRole("button", { name: /Restore/ }));
+    await waitFor(() =>
+      expect(api.files.restore).toHaveBeenCalledWith({ home: "me" }, "abc12345", undefined)
+    );
+  });
+
+  it("opens an admin's Trash on one folder per user, each opening that user's Trash", async () => {
+    vi.mocked(api.files.allTrash).mockResolvedValue({
+      items: [
+        {
+          id: "bob12345",
+          name: "old",
+          laneId: null,
+          path: "old",
+          isDir: true,
+          deletedAt: "2026-10-15T08:00:00.000Z",
+          store: "host",
+          home: "bob",
+          owner: "Bob",
+        },
+      ],
+      errors: [{ home: "me", owner: "An", message: "EMEMBERGONE" }],
+    });
+    vi.mocked(api.files.trash).mockResolvedValue({
+      items: [
+        {
+          id: "bob12345",
+          name: "old",
+          laneId: null,
+          path: "old",
+          isDir: true,
+          deletedAt: "2026-10-15T08:00:00.000Z",
+          store: "host",
+        },
+      ],
+    });
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    const trashes = screen.getByTestId("fx-trashes");
+    expect(within(trashes).getAllByRole("button")).toHaveLength(1);
+    await user.click(within(trashes).getByRole("button", { name: "Trash" }));
+    const folders = await screen.findAllByTestId("fx-trash-folder");
+    expect(folders.map((f) => f.textContent)).toEqual(["My TrashEMEMBERGONE", "Bob1 item(s)"]);
+    expect(screen.queryByTestId("fx-trash-row")).toBeNull();
+    await user.click(folders[1]!);
+    await waitFor(() => expect(api.files.trash).toHaveBeenLastCalledWith({ home: "bob" }));
+    expect(screen.getByRole("navigation", { name: "Location" }).textContent).toContain("Bob");
+    const trashRow = await screen.findByTestId("fx-trash-row");
+    await user.click(within(trashRow).getByRole("button", { name: /Delete forever/ }));
+    await waitFor(() =>
+      expect(confirmDialog).toHaveBeenCalledWith(
+        expect.objectContaining({ message: expect.stringContaining("Bob's Trash") })
+      )
+    );
+    expect(api.files.purge).not.toHaveBeenCalled();
+    vi.mocked(confirmDialog).mockResolvedValueOnce(true);
+    await user.click(within(trashRow).getByRole("button", { name: /Delete forever/ }));
+    await waitFor(() =>
+      expect(api.files.purge).toHaveBeenCalledWith({ home: "bob" }, "bob12345", "host")
+    );
+    // Back to the folders through the path bar.
+    await user.click(
+      within(screen.getByRole("navigation", { name: "Location" })).getByRole("button", {
+        name: "Trash",
+      })
+    );
+    expect(await screen.findAllByTestId("fx-trash-folder")).toHaveLength(2);
+  });
+
+  it("right-clicks a Trash folder to empty it, and a Trash row to restore it", async () => {
+    vi.mocked(api.files.allTrash).mockResolvedValue({
+      items: [
+        {
+          id: "bob12345",
+          name: "old",
+          laneId: null,
+          path: "old",
+          isDir: true,
+          deletedAt: "2026-10-15T08:00:00.000Z",
+          store: "host",
+          home: "bob",
+          owner: "Bob",
+        },
+      ],
+      errors: [],
+    });
+    vi.mocked(api.files.trash).mockResolvedValue({
+      items: [
+        {
+          id: "bob12345",
+          name: "old",
+          laneId: null,
+          path: "old",
+          isDir: true,
+          deletedAt: "2026-10-15T08:00:00.000Z",
+          store: "host",
+        },
+      ],
+    });
+    vi.mocked(api.files.restore).mockResolvedValue({ path: "old", laneId: null });
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    await user.click(
+      within(screen.getByTestId("fx-trashes")).getByRole("button", { name: "Trash" })
+    );
+    const folders = await screen.findAllByTestId("fx-trash-folder");
+    // My Trash is empty: its Empty Trash is disabled.
+    fireEvent.contextMenu(folders[0]!);
+    expect(
+      within(screen.getByTestId("fx-trash-root-menu")).getByRole("menuitem", {
+        name: "Empty Trash",
+      })
+    ).toHaveProperty("disabled", true);
+    fireEvent.keyDown(document, { key: "Escape" });
+    fireEvent.contextMenu(folders[1]!);
+    vi.mocked(confirmDialog).mockResolvedValueOnce(true);
+    await user.click(
+      within(screen.getByTestId("fx-trash-root-menu")).getByRole("menuitem", {
+        name: "Empty Trash",
+      })
+    );
+    await waitFor(() => expect(api.files.purge).toHaveBeenCalledWith({ home: "bob" }, "all"));
+    expect(screen.queryByTestId("fx-trash-root-menu")).toBeNull();
+
+    fireEvent.contextMenu((await screen.findAllByTestId("fx-trash-folder"))[1]!);
+    await user.click(
+      within(screen.getByTestId("fx-trash-root-menu")).getByRole("menuitem", { name: "Open" })
+    );
+    fireEvent.contextMenu(await screen.findByTestId("fx-trash-row"));
+    await user.click(
+      within(screen.getByTestId("fx-trash-menu")).getByRole("menuitem", { name: "Restore" })
+    );
+    await waitFor(() =>
+      expect(api.files.restore).toHaveBeenCalledWith({ home: "bob" }, "bob12345", "host")
+    );
+  });
+
+  it("right-clicks a sidebar workspace and a path crumb", async () => {
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    fireEvent.contextMenu(screen.getByRole("button", { name: "two" }));
+    await user.click(
+      within(screen.getByTestId("fx-place-menu")).getByRole("menuitem", { name: "Open" })
+    );
+    await waitFor(() => expect(api.files.list).toHaveBeenLastCalledWith(2, ""));
+    fireEvent.contextMenu(screen.getByRole("button", { name: "Home" }));
+    await user.click(
+      within(screen.getByTestId("fx-place-menu")).getByRole("menuitem", { name: "Open Trash" })
+    );
+    await waitFor(() => expect(api.files.trash).toHaveBeenLastCalledWith({ home: "me" }));
+  });
+
+  it("shows why a Trash could not be read instead of an empty one", async () => {
+    vi.mocked(api.files.trash).mockRejectedValue(new Error("ENOENT: no such folder"));
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    await user.click(
+      within(screen.getByTestId("fx-trashes")).getByRole("button", { name: "Trash" })
+    );
+    await user.click(await screen.findByRole("button", { name: /My Trash/ }));
+    expect(await screen.findByText(/ENOENT: no such folder/)).toBeTruthy();
+    expect(screen.queryByText("The Trash is empty.")).toBeNull();
+  });
+
+  it("opens the user's home from the sidebar, and pastes from it into a workspace", async () => {
+    vi.mocked(api.files.copy).mockResolvedValue({ copied: ["a.txt"] });
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    await user.click(await screen.findByRole("button", { name: "Home" }));
+    await waitFor(() => expect(api.files.list).toHaveBeenLastCalledWith({ home: "me" }, ""));
+    fireEvent.click(row("a.txt"));
+    fireEvent.keyDown(screen.getByTestId("fx-list"), { key: "c", ctrlKey: true });
+    await user.click(screen.getByRole("button", { name: "one" }));
+    await waitFor(() => expect(api.files.list).toHaveBeenLastCalledWith(1, ""));
+    await user.click(screen.getByRole("button", { name: /Paste 1 item/ }));
+    await waitFor(() =>
+      expect(api.files.copy).toHaveBeenCalledWith(1, ["a.txt"], "", {
+        fromHome: "me",
+        conflict: "fail",
+      })
+    );
+  });
+
+  it("shows another user's home read-only: no New, Upload, Cut, Rename or Delete", async () => {
+    const user = userEvent.setup();
+    open();
+    await screen.findByText("a.txt");
+    await user.click(await screen.findByRole("button", { name: "Bob" }));
+    expect(await screen.findByTestId("fx-readonly")).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "New" })).toBeNull();
+    expect(screen.queryByRole("button", { name: "Upload" })).toBeNull();
+    await user.click(row("a.txt"));
+    const bar = screen.getByTestId("fx-actionbar");
+    expect(within(bar).getByRole("button", { name: /Download/ })).toBeInTheDocument();
+    expect(within(bar).getByRole("button", { name: /Copy/ })).toBeInTheDocument();
+    expect(within(bar).queryByRole("button", { name: /Cut|Rename|Move to Trash/ })).toBeNull();
+    fireEvent.keyDown(screen.getByTestId("fx-list"), { key: "Delete" });
+    expect(api.files.remove).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,206 @@
+/**
+ * @file FolderBrowseModal.test.tsx
+ * @description Unit tests for the in-app folder browser laid out like a
+ * native picker: a click selects and Select picks that folder (else the
+ * current one), a double-click opens, Backspace and the breadcrumb go up,
+ * the filter narrows the list, Places open Home and a workspace, the path
+ * field (Ctrl+L) opens a typed path, New folder makes one and selects it,
+ * Show hidden re-lists with dot entries, and a Select is remembered as Recent.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { api } from "../../../lib/api";
+import { FolderBrowseModal } from "../FolderBrowseModal";
+
+vi.mock("../../../lib/api", () => ({
+  api: { lanes: { browse: vi.fn(), mkdir: vi.fn(), list: vi.fn() } },
+}));
+
+const TREE: Record<string, string[]> = {
+  "/home/u": ["proj", "notes"],
+  "/home/u/proj": ["api", "web"],
+  "/home/u/proj/api": [],
+  "/home/u/proj/web": [],
+  "/home/u/notes": [],
+  "/srv/ws": [],
+};
+
+function listing(p: string, hidden = false) {
+  const names = [...(TREE[p] ?? []), ...(hidden ? [".cfg"] : [])];
+  return {
+    path: p,
+    parent: p === "/home/u" ? null : p.slice(0, p.lastIndexOf("/")) || "/",
+    home: "/home/u",
+    entries: names.map((n, i) => ({
+      name: n,
+      path: `${p}/${n}`,
+      isGitRepo: n === "api",
+      mtime: 1_700_000_000_000 + i,
+    })),
+  };
+}
+
+beforeEach(() => {
+  localStorage.clear();
+  vi.mocked(api.lanes.browse)
+    .mockReset()
+    .mockImplementation(async (p?: string, _f?: boolean, hidden?: boolean) => {
+      const at = p || "/home/u";
+      if (!(at in TREE)) throw new Error("path does not exist");
+      return listing(at, hidden);
+    });
+  vi.mocked(api.lanes.mkdir).mockReset();
+  vi.mocked(api.lanes.list)
+    .mockReset()
+    .mockResolvedValue({
+      lanes: [{ id: 1, title: "Shop API", cwd: "/srv/ws" }],
+      counts: {},
+    } as never);
+});
+
+const open = (onSelect = vi.fn(), initialPath?: string) => {
+  render(
+    <FolderBrowseModal open initialPath={initialPath} onSelect={onSelect} onClose={vi.fn()} />
+  );
+  return screen.findByRole("dialog", { name: "Browse for a folder" });
+};
+
+const option = (dialog: HTMLElement, name: string) =>
+  within(dialog).findByRole("option", { name: new RegExp(name) });
+
+describe("FolderBrowseModal", () => {
+  it("opens an admin in their own home; the Server folder tick opens the host's", async () => {
+    const user = userEvent.setup();
+    vi.mocked(api.lanes.browse).mockImplementation(async (p, _f, _h, host) => ({
+      ...listing(p || (host ? "/home/u" : "/srv/ws"), false),
+      home: host ? "/home/u" : "/srv/ws",
+      hostHome: "/home/u",
+    }));
+    const dialog = await open();
+    await waitFor(() =>
+      expect(api.lanes.browse).toHaveBeenLastCalledWith(undefined, false, false, false)
+    );
+    const tick = within(dialog).getByTestId("browse-host-folder");
+    expect(tick).not.toBeChecked();
+    await user.click(tick);
+    await waitFor(() =>
+      expect(api.lanes.browse).toHaveBeenLastCalledWith(undefined, false, false, true)
+    );
+    expect(tick).toBeChecked();
+  });
+
+  it("shows no Server folder tick without a host home in the listing", async () => {
+    const dialog = await open();
+    expect((await within(dialog).findAllByRole("option")).length).toBeGreaterThan(0);
+    expect(within(dialog).queryByTestId("browse-host-folder")).toBeNull();
+  });
+
+  it("click selects, double-click opens, Select picks the selection else the folder", async () => {
+    const onSelect = vi.fn();
+    const dialog = await open(onSelect);
+    await userEvent.click(await option(dialog, "proj"));
+    expect(await option(dialog, "proj")).toHaveAttribute("aria-selected", "true");
+    await userEvent.dblClick(await option(dialog, "proj"));
+    await option(dialog, "web");
+    await userEvent.click(within(dialog).getByRole("button", { name: "Select this folder" }));
+    expect(onSelect).toHaveBeenCalledWith("/home/u/proj");
+  });
+
+  it("Enter opens the selected folder and Backspace goes back up to it", async () => {
+    const dialog = await open();
+    const list = within(dialog).getByRole("listbox");
+    await userEvent.click(await option(dialog, "proj"));
+    await userEvent.keyboard("{Enter}");
+    await option(dialog, "api");
+    list.focus();
+    await userEvent.keyboard("{Backspace}");
+    await waitFor(() =>
+      expect(within(dialog).getByRole("option", { name: /proj/ })).toHaveAttribute(
+        "aria-selected",
+        "true"
+      )
+    );
+  });
+
+  it("the breadcrumb, Back and Forward move between folders", async () => {
+    const dialog = await open(vi.fn(), "/home/u/proj/api");
+    await userEvent.click(within(dialog).getByRole("button", { name: "proj" }));
+    await option(dialog, "web");
+    await userEvent.click(within(dialog).getByRole("button", { name: /^Back/ }));
+    await waitFor(() =>
+      expect(api.lanes.browse).toHaveBeenLastCalledWith("/home/u/proj/api", false, false, false)
+    );
+    await userEvent.click(within(dialog).getByRole("button", { name: /^Forward/ }));
+    await waitFor(() =>
+      expect(api.lanes.browse).toHaveBeenLastCalledWith("/home/u/proj", false, false, false)
+    );
+    // Above the user's own folder (it answered no parent) nothing is a link.
+    await userEvent.click(within(dialog).getByRole("button", { name: /^Home$/ }));
+    await option(dialog, "notes");
+    expect(within(dialog).getByRole("button", { name: "home" })).toBeDisabled();
+  });
+
+  it("the filter narrows the list, and Enter on a single match opens it", async () => {
+    const dialog = await open();
+    await option(dialog, "notes");
+    await userEvent.type(within(dialog).getByRole("textbox", { name: "Filter…" }), "pro");
+    expect(within(dialog).queryByRole("option", { name: /notes/ })).toBeNull();
+    await userEvent.keyboard("{Enter}");
+    await option(dialog, "web");
+  });
+
+  it("Places open a workspace and Home; Ctrl+L opens a typed path", async () => {
+    const dialog = await open(vi.fn(), "/home/u/proj");
+    await userEvent.click(await within(dialog).findByRole("button", { name: /Shop API/ }));
+    await waitFor(() =>
+      expect(api.lanes.browse).toHaveBeenLastCalledWith("/srv/ws", false, false, false)
+    );
+    await userEvent.click(within(dialog).getByRole("button", { name: /^Home$/ }));
+    await option(dialog, "notes");
+    await userEvent.keyboard("{Control>}l{/Control}");
+    const field = within(dialog).getByRole("textbox", { name: "Type a path (Ctrl+L)" });
+    await userEvent.clear(field);
+    await userEvent.type(field, "/home/u/proj/web{Enter}");
+    await waitFor(() =>
+      expect(api.lanes.browse).toHaveBeenLastCalledWith("/home/u/proj/web", false, false, false)
+    );
+  });
+
+  it("New folder makes one in the current folder and selects it", async () => {
+    vi.mocked(api.lanes.mkdir).mockImplementation(async (parent, name) => {
+      TREE[parent] = [...(TREE[parent] ?? []), name];
+      return { path: `${parent}/${name}` };
+    });
+    const dialog = await open();
+    await option(dialog, "proj");
+    await userEvent.click(within(dialog).getByRole("button", { name: /New folder/ }));
+    await userEvent.type(
+      within(dialog).getByRole("textbox", { name: "Folder name" }),
+      "fresh{Enter}"
+    );
+    expect(api.lanes.mkdir).toHaveBeenCalledWith("/home/u", "fresh");
+    await waitFor(async () =>
+      expect(await option(dialog, "fresh")).toHaveAttribute("aria-selected", "true")
+    );
+    TREE["/home/u"] = ["proj", "notes"];
+  });
+
+  it("Show hidden re-lists with dot entries, and a pick is kept as Recent", async () => {
+    const onSelect = vi.fn();
+    const dialog = await open(onSelect);
+    await option(dialog, "proj");
+    expect(within(dialog).queryByRole("option", { name: /\.cfg/ })).toBeNull();
+    await userEvent.click(within(dialog).getByRole("checkbox", { name: /Show hidden/ }));
+    await option(dialog, "\\.cfg");
+    await userEvent.dblClick(await option(dialog, "proj"));
+    await option(dialog, "web");
+    await userEvent.click(within(dialog).getByRole("button", { name: "Select this folder" }));
+    expect(onSelect).toHaveBeenCalledWith("/home/u/proj");
+    expect(JSON.parse(localStorage.getItem("agenthub.browse.recent") || "[]")).toEqual([
+      "/home/u/proj",
+    ]);
+  });
+});

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__/LaneChangesPanel.test.tsx

@@ -15,7 +15,7 @@
  */
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, waitFor, act, within } from "@testing-library/react";
+import { render, screen, waitFor, act, within, fireEvent } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { LaneChangesPanel, gitChangeFor } from "../LaneChangesPanel";
 import { confirmDialog, confirmDiscard } from "../../../lib/confirm";
@@ -24,6 +24,12 @@ import type { LaneChanges } from "../../../lib/types";
 
 // The themed confirm needs its host (App); answer it here.
 // CodeMirror does not run in jsdom: the editor is a textarea over the same props.
+// Local mode unless a test says otherwise.
+const perms = vi.hoisted(() => ({ local: true }));
+vi.mock("../../AuthGate", async (importOriginal) => {
+  const m = await importOriginal<typeof import("../../AuthGate")>();
+  return { ...m, usePermissions: () => ({ ...m.usePermissions(), local: perms.local }) };
+});
 vi.mock("../DiffEditor", () => ({
   default: (p: {
     value: string;
@@ -75,6 +81,9 @@ vi.mock("../../../lib/api", () => ({
       gitTree: vi.fn(),
       gitTreeAll: vi.fn(),
       gitBlame: vi.fn(),
+      gitDownloadUrl: (id: number, path: string) =>
+        `/api/lanes/${id}/git/download?path=${encodeURIComponent(path)}`,
+      gitUpload: vi.fn(),
     },
   },
 }));
@@ -143,6 +152,7 @@ function discardOf(path: string) {
 }
 
 beforeEach(() => {
+  perms.local = true;
   vi.mocked(api.lanes.git).mockReset().mockResolvedValue({ available: false });
   vi.mocked(api.lanes.changes).mockReset();
   vi.mocked(api.lanes.changes).mockResolvedValue(changes());
@@ -255,6 +265,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} />);
@@ -277,16 +317,29 @@ describe("LaneChangesPanel", () => {
     await waitFor(() => expect(api.lanes.changes).toHaveBeenCalledWith(7, { range: "branch" }));
   });
 
-  it("says so, quietly, when the lane's directory is not a git repo", async () => {
+  it("says so, quietly, beside the tree at full width, when the folder is not a repo", async () => {
+    vi.mocked(api.lanes.changes).mockResolvedValue({
+      available: false,
+      range: "work",
+      files: [],
+    });
+    render(<LaneChangesPanel laneId={7} full />);
+    expect(
+      await screen.findByText("This workspace's directory is not a readable git repository.")
+    ).toBeInTheDocument();
+  });
+
+  it("opens on Files, its only tab, when the workspace folder is not a repo", async () => {
     vi.mocked(api.lanes.changes).mockResolvedValue({
       available: false,
       range: "work",
       files: [],
     });
     render(<LaneChangesPanel laneId={7} />);
-    expect(
-      await screen.findByText("This workspace's directory is not a readable git repository.")
-    ).toBeInTheDocument();
+    expect(await screen.findByTestId("lane-changes-browse")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Files" })).toHaveAttribute("aria-pressed", "true");
+    for (const name of ["Changes", "Review", "History"])
+      expect(screen.queryByRole("button", { name })).not.toBeInTheDocument();
   });
 
   it("adds an unversioned file to VCS, for that path alone, and ticks it", async () => {
@@ -515,6 +568,94 @@ describe("LaneChangesPanel", () => {
     expect(screen.queryByTestId("lane-file-edit")).toBeNull();
   });
 
+  it("reads a folder again on every open, so files added since show (not a stale empty level)", async () => {
+    let filled = false;
+    vi.mocked(api.lanes.gitTree).mockImplementation(async (_t, path = "") => ({
+      available: true,
+      path,
+      entries:
+        path === "src"
+          ? filled
+            ? [{ name: "app.ts", path: "src/app.ts", dir: false }]
+            : []
+          : [{ name: "src", path: "src", dir: true }],
+      truncated: false,
+    }));
+    const user = userEvent.setup();
+    const { rerender } = render(<LaneChangesPanel laneId={7} full />);
+    const sidebar = await screen.findByTestId("lane-changes-sidebar");
+    await user.click(await within(sidebar).findByText("src"));
+    await waitFor(() => expect(api.lanes.gitTree).toHaveBeenCalledWith(7, "src"));
+    expect(within(sidebar).queryByText("app.ts")).toBeNull();
+    // Source arrives from outside the panel (the File Explorer, a terminal).
+    filled = true;
+    await user.click(within(sidebar).getByText("src")); // close
+    await user.click(within(sidebar).getByText("src")); // open again → read again
+    expect(await within(sidebar).findByText("app.ts")).toBeInTheDocument();
+    // And the header's File Explorer reports a change: open folders re-read.
+    filled = false;
+    rerender(<LaneChangesPanel laneId={7} full filesChanged={1} />);
+    await waitFor(() => expect(within(sidebar).queryByText("app.ts")).toBeNull());
+  });
+
+  it("uploads files into a folder from the tree menu, and downloads a file (issue #78)", async () => {
+    perms.local = false;
+    vi.mocked(api.lanes.gitTree).mockImplementation(async (_t, path = "") => ({
+      available: true,
+      path,
+      entries:
+        path === "out"
+          ? [{ name: "report.md", path: "out/report.md", dir: false }]
+          : [{ name: "out", path: "out", dir: true }],
+      truncated: false,
+    }));
+    vi.mocked(api.lanes.gitUpload).mockResolvedValue({ path: "out/data.csv" });
+    const user = userEvent.setup();
+    render(<LaneChangesPanel laneId={7} full />);
+    const sidebar = await screen.findByTestId("lane-changes-sidebar");
+    const input = within(sidebar).getByTestId("lane-changes-upload-input") as HTMLInputElement;
+    const picked = vi.spyOn(input, "click").mockImplementation(() => {});
+    await user.pointer({ keys: "[MouseRight]", target: await within(sidebar).findByText("out") });
+    await user.click(screen.getByTestId("lane-changes-menu-upload"));
+    expect(picked).toHaveBeenCalled();
+    const file = new File(["a,b\n"], "data.csv", { type: "text/csv" });
+    fireEvent.change(input, { target: { files: [file] } });
+    await waitFor(() => expect(api.lanes.gitUpload).toHaveBeenCalledWith(7, "out", file));
+    // The folder it landed in is re-read and opened.
+    expect(await within(sidebar).findByText("report.md")).toBeInTheDocument();
+
+    const clicked: string[] = [];
+    const anchor = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(function (
+      this: HTMLAnchorElement
+    ) {
+      clicked.push(this.getAttribute("href") ?? "");
+    });
+    await user.pointer({ keys: "[MouseRight]", target: within(sidebar).getByText("report.md") });
+    await user.click(screen.getByTestId("lane-changes-menu-download"));
+    expect(clicked).toEqual(["/api/lanes/7/git/download?path=out%2Freport.md"]);
+    anchor.mockRestore();
+    picked.mockRestore();
+  });
+
+  it("offers no upload, download or File Explorer in local mode", async () => {
+    vi.mocked(api.lanes.gitTree).mockImplementation(async (_t, path = "") => ({
+      available: true,
+      path,
+      entries:
+        path === "out"
+          ? [{ name: "report.md", path: "out/report.md", dir: false }]
+          : [{ name: "out", path: "out", dir: true }],
+      truncated: false,
+    }));
+    const user = userEvent.setup();
+    render(<LaneChangesPanel laneId={7} full />);
+    const sidebar = await screen.findByTestId("lane-changes-sidebar");
+    await user.pointer({ keys: "[MouseRight]", target: await within(sidebar).findByText("out") });
+    expect(screen.getByTestId("lane-changes-tree-menu")).toBeInTheDocument();
+    expect(screen.queryByTestId("lane-changes-menu-upload")).toBeNull();
+    expect(screen.queryByTestId("lane-changes-menu-explorer")).toBeNull();
+  });
+
   it("at full width shows the tree as a sidebar and opens a file straight in the editor", async () => {
     vi.mocked(api.lanes.gitTree).mockResolvedValue({
       available: true,
@@ -1657,6 +1798,24 @@ describe("LaneChangesPanel", () => {
     expect(screen.getByTestId("lane-file-view")).toBeInTheDocument();
   });
 
+  it("opens a file from Files when the workspace folder is not a repo", async () => {
+    const user = userEvent.setup();
+    vi.mocked(api.lanes.changes).mockResolvedValue({
+      available: false,
+      range: "work",
+      files: [],
+    });
+    render(<Tabbed laneId={7} />);
+    await screen.findByTestId("lane-changes-browse");
+
+    await user.type(await screen.findByLabelText("Find a file by path…"), "main");
+    await user.click(await screen.findByText("src/main.ts"));
+    expect(await screen.findByTestId("lane-file-view")).toHaveTextContent("const whole = 1;");
+    expect(
+      screen.queryByText("This workspace's directory is not a readable git repository.")
+    ).toBeNull();
+  });
+
   it("keeps the overview rows mounted across re-renders (typing in the commit box)", async () => {
     const user = userEvent.setup();
     render(<LaneChangesPanel laneId={7} />);

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

@@ -21,7 +21,7 @@ import type { LaneGitFacts } from "../../../lib/types";
 vi.mock("../../../lib/confirm", () => ({ confirmDialog: vi.fn(async () => true) }));
 vi.mock("../../../lib/api", () => ({
   gitTarget: (lane: number, session?: string | null) => (session ? { lane, session } : lane),
-  api: { lanes: { gitAction: vi.fn(), gitBranches: vi.fn() } },
+  api: { lanes: { gitAction: vi.fn(), gitBranches: vi.fn(), git: vi.fn() } },
 }));
 
 function facts(over: Partial<Extract<LaneGitFacts, { available: true }>> = {}): LaneGitFacts {
@@ -164,6 +164,29 @@ describe("LaneGitBar", () => {
     expect(api.lanes.gitAction).not.toHaveBeenCalled();
   });
 
+  it("says there is nothing to push instead of asking to push zero commits", async () => {
+    const user = userEvent.setup();
+    vi.mocked(confirmDialog).mockClear();
+    vi.mocked(api.lanes.git).mockResolvedValueOnce(facts({ ahead: 0 }));
+    render(<LaneGitBar laneId={3} git={facts({ ahead: 0 })} onChanged={vi.fn()} />);
+    await user.click(screen.getByRole("button", { name: /^Push$/ }));
+    await waitFor(() => expect(api.lanes.git).toHaveBeenCalledWith(3));
+    expect(confirmDialog).not.toHaveBeenCalled();
+    expect(api.lanes.gitAction).not.toHaveBeenCalled();
+  });
+
+  it("re-reads stale facts: a commit made since still gets the push confirm", async () => {
+    const user = userEvent.setup();
+    vi.mocked(api.lanes.git).mockResolvedValueOnce(facts({ ahead: 1 }));
+    render(<LaneGitBar laneId={3} git={facts({ ahead: 0 })} onChanged={vi.fn()} />);
+    await user.click(screen.getByRole("button", { name: /^Push$/ }));
+    await waitFor(() =>
+      expect(confirmDialog).toHaveBeenLastCalledWith(
+        expect.objectContaining({ message: expect.stringContaining("Push 1 commit") })
+      )
+    );
+  });
+
   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

@@ -14,7 +14,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 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 { MemoryRouter, Route, Routes, useLocation, useSearchParams } from "react-router-dom";
 import type { Lane, Session } from "../../../lib/types";
 import type { LaneSourcesView, RunHandle } from "../../../lib/api";
 
@@ -241,6 +241,27 @@ describe("WorkspaceHome", () => {
     await waitFor(() => expect(localStorage.getItem("agenthub.workspace.draft.1")).toBeNull());
   });
 
+  it("drops the sent prompt's draft even though opening the session unmounts the home", async () => {
+    // As the Workspace page: `&run=` replaces the home with the session view.
+    function HomeUntilRun() {
+      const [params] = useSearchParams();
+      return params.get("run") ? null : <WorkspaceHome lane={lane()} onMenuAction={() => undefined} />;
+    }
+    const user = userEvent.setup();
+    render(
+      <MemoryRouter initialEntries={["/workspace?lane=1"]}>
+        <Routes>
+          <Route path="*" element={<HomeUntilRun />} />
+        </Routes>
+      </MemoryRouter>
+    );
+    await screen.findByTestId("workspace-recent-s-live");
+    await user.type(screen.getByLabelText("How can I help you today?"), "sent once");
+    await user.click(screen.getByTestId("workspace-home-start"));
+    await waitFor(() => expect(screen.queryByTestId("workspace-home-start")).toBeNull());
+    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");

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,247 @@
+/**
+ * @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 if (rect.top > 200) {
+      style = { left, top: rect.top - 12, transform: "translateY(-100%)" };
+    } else {
+      // A target filling the screen (the live session): no room above or
+      // below, so the card sits inside its bottom-right corner.
+      style = {
+        left: Math.min(Math.max(12, rect.right - W - 16), window.innerWidth - W - 12),
+        top: Math.min(rect.bottom, window.innerHeight) - 16,
+        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();
+    }
+  });
+});

client/src/components/run/ChatAddMenu.tsx

@@ -0,0 +1,430 @@
+/**
+ * @file ChatAddMenu.tsx
+ * @description The Chat view's `+` menu, Claude Desktop's: Upload or add
+ * files (the prompt box's own picker), what is already there to attach —
+ * Project files (a search of the box's folder, folders too:
+ * `GET /api/run/files?dirs=1`, sent as `@path`), the workspace's Context
+ * files (`GET /api/lanes/:id/sources`) and Recent uploads (this browser's,
+ * `lib/promptAttach.ts`) —, Skills (the user's and the project's)
+ * and Plugins → one plugin → the skills and commands it ships. Picking one
+ * puts `/<name>` (`/<plugin>:<name>`) at the front of the message — the same
+ * text the `/` autocomplete inserts, so the CLI runs it as typed. Both lists
+ * are read when the menu first opens (`GET /api/cc-config/skills|plugins`),
+ * and Manage opens the Claude config page on that tab.
+ * @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 {
+  ChevronRight,
+  FileText,
+  FolderOpen,
+  History,
+  Paperclip,
+  Plug,
+  Plus,
+  ScrollText,
+  Settings2,
+} from "lucide-react";
+import { api } from "../../lib/api";
+import { projectAttachment, recentUploads, type Attachment } from "../../lib/promptAttach";
+
+interface Entry {
+  name: string;
+  description?: string;
+}
+interface Lists {
+  skills: Entry[];
+  plugins: { name: string; items: Entry[] }[];
+}
+
+const byName = (a: Entry, b: Entry) => a.name.localeCompare(b.name);
+
+function loadLists(cwd: string): Promise<Lists> {
+  return Promise.all([
+    api.ccConfig.skills(undefined, cwd).catch(() => ({ items: [] })),
+    api.ccConfig.plugins().catch(() => ({ plugins: [] })),
+  ]).then(([sk, pl]) => ({
+    skills: sk.items
+      .map((s) => ({ name: s.name, description: s.frontmatter?.description }))
+      .filter((s, i, all) => all.findIndex((o) => o.name === s.name) === i)
+      .sort(byName),
+    plugins: pl.plugins
+      .filter((p) => p.enabled !== false && p.contributes)
+      .map((p) => ({
+        name: p.name,
+        items: [...p.contributes!.items.skills, ...p.contributes!.items.commands]
+          .map((it) => ({ name: it.name, description: it.description ?? undefined }))
+          .filter((it, i, all) => all.findIndex((o) => o.name === it.name) === i)
+          .sort(byName),
+      }))
+      .filter((p, i, all) => p.items.length > 0 && all.findIndex((o) => o.name === p.name) === i)
+      .sort(byName),
+  }));
+}
+
+const PANEL =
+  "absolute w-60 rounded-xl border border-border bg-surface-1 py-1 shadow-lg animate-fade-in";
+const ROW =
+  "flex w-full items-center gap-2.5 px-3 py-1.5 text-left text-sm text-fg-secondary hover:bg-surface-3 hover:text-fg-primary";
+
+function Row({
+  icon,
+  label,
+  more,
+  active,
+  onClick,
+  onHover,
+  title,
+  testId,
+}: {
+  icon: ReactNode;
+  label: string;
+  more?: boolean;
+  active?: boolean;
+  onClick: () => void;
+  onHover?: () => void;
+  title?: string;
+  testId?: string;
+}) {
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      title={title}
+      data-testid={testId}
+      onClick={onClick}
+      onMouseEnter={onHover}
+      className={`${ROW} ${active ? "bg-surface-3 text-fg-primary" : ""}`}
+    >
+      <span className="shrink-0 text-fg-muted">{icon}</span>
+      <span className="min-w-0 flex-1 truncate">{label}</span>
+      {more && <ChevronRight className="h-3.5 w-3.5 shrink-0 text-fg-muted" />}
+    </button>
+  );
+}
+
+/** Project files: a search of the box's folder, shortest paths first. */
+function ProjectFiles({ cwd, onPick }: { cwd: string; onPick: (rel: string) => void }) {
+  const { t } = useTranslation("run");
+  const [q, setQ] = useState("");
+  const [items, setItems] = useState<string[] | null>(null);
+  useEffect(() => {
+    let live = true;
+    const tid = window.setTimeout(() => {
+      api.run
+        .files(cwd, q, true)
+        .then((r) => live && setItems(r.items))
+        .catch(() => live && setItems([]));
+    }, 120);
+    return () => {
+      live = false;
+      window.clearTimeout(tid);
+    };
+  }, [cwd, q]);
+  return (
+    <>
+      <input
+        autoFocus
+        value={q}
+        onChange={(e) => setQ(e.target.value)}
+        placeholder={t("chat.searchFiles")}
+        data-testid="chat-add-project-search"
+        className="mx-2 mb-1 w-[calc(100%-1rem)] rounded-md border border-border bg-surface-2 px-2 py-1 text-xs text-fg-primary placeholder:text-fg-muted focus:border-accent/50 focus:outline-none"
+      />
+      <div className="max-h-72 overflow-y-auto">
+        {!items || items.length === 0 ? (
+          <p className="px-3 py-1.5 text-xs text-fg-muted">{items ? t("chat.none") : "…"}</p>
+        ) : (
+          items.map((p) => (
+            <Row
+              key={p}
+              icon={
+                p.endsWith("/") ? (
+                  <FolderOpen className="h-4 w-4" />
+                ) : (
+                  <FileText className="h-4 w-4" />
+                )
+              }
+              label={p}
+              title={p}
+              testId={`chat-add-project-${p}`}
+              onClick={() => onPick(p)}
+            />
+          ))
+        )}
+      </div>
+    </>
+  );
+}
+
+type Sub = "project" | "context" | "recent" | "skills" | "plugins";
+
+export function ChatAddMenu({
+  cwd,
+  laneId = null,
+  skills,
+  onUpload,
+  onInsert,
+  onAttach,
+}: {
+  cwd: string;
+  /** The workspace, for its Context files; none hides them. */
+  laneId?: number | null;
+  /** Offer Skills and Plugins: Claude only, they are Claude Code's. */
+  skills: boolean;
+  onUpload: () => void;
+  /** `/<name>` picked. */
+  onInsert: (command: string) => void;
+  /** An existing file picked: a project path, a context file, an upload. */
+  onAttach: (items: Attachment[]) => void;
+}) {
+  const { t } = useTranslation("run");
+  const navigate = useNavigate();
+  const [open, setOpen] = useState(false);
+  const [sub, setSub] = useState<Sub | null>(null);
+  const [context, setContext] = useState<Attachment[] | null>(null);
+  const [recent, setRecent] = useState<Attachment[]>([]);
+  const [plugin, setPlugin] = useState<string | null>(null);
+  const [lists, setLists] = useState<Lists | null>(null);
+  const ref = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    if (skills && !lists) void loadLists(cwd).then(setLists);
+
+    const away = (e: MouseEvent) => {
+      if (!ref.current?.contains(e.target as Node)) setOpen(false);
+    };
+    const esc = (e: KeyboardEvent) => e.key === "Escape" && setOpen(false);
+    document.addEventListener("mousedown", away);
+    document.addEventListener("keydown", esc);
+    return () => {
+      document.removeEventListener("mousedown", away);
+      document.removeEventListener("keydown", esc);
+    };
+  }, [open, skills, lists, cwd]);
+
+  // Read again at each opening: either list may have grown since.
+  useEffect(() => {
+    if (!open) return;
+    setRecent(recentUploads());
+    setContext(null);
+    if (laneId === null) return;
+    let live = true;
+    api.lanes
+      .sources(laneId)
+      .then(
+        (v) =>
+          live &&
+          setContext(
+            v.sources
+              .filter((s) => s.kind === "file" && !s.missing)
+              .map((s) => ({ path: `@${s.path}`, name: s.name }))
+          )
+      )
+      .catch(() => live && setContext([]));
+    return () => {
+      live = false;
+    };
+  }, [open, laneId]);
+
+  const close = () => {
+    setOpen(false);
+    setSub(null);
+    setPlugin(null);
+  };
+  const pick = (command: string) => {
+    close();
+    onInsert(command);
+  };
+  const attach = (item: Attachment) => {
+    close();
+    onAttach([item]);
+  };
+  const manage = (tab: "skills" | "plugins") => {
+    close();
+    navigate(`/cc-config?tab=${tab}`);
+  };
+
+  const entries = (items: Entry[], prefix: string, from?: string) =>
+    items.length === 0 ? (
+      <p className="px-3 py-1.5 text-xs text-fg-muted">{lists ? t("chat.none") : "…"}</p>
+    ) : (
+      items.map((it) => (
+        <Row
+          key={it.name}
+          icon={<ScrollText className="h-4 w-4" />}
+          label={it.name}
+          title={[it.description, from].filter(Boolean).join("\n") || undefined}
+          testId={`chat-add-skill-${prefix}${it.name}`}
+          onClick={() => pick(`/${prefix}${it.name}`)}
+        />
+      ))
+    );
+  const shownPlugin = lists?.plugins.find((p) => p.name === plugin);
+
+  return (
+    <div ref={ref} className="relative">
+      <button
+        type="button"
+        data-testid="chat-add"
+        aria-label={t("chat.add")}
+        title={t("chat.add")}
+        aria-expanded={open}
+        onClick={() => (open ? close() : setOpen(true))}
+        className="flex h-8 w-8 items-center justify-center rounded-full text-fg-muted transition-colors hover:bg-surface-3 hover:text-fg-primary"
+      >
+        <Plus className="h-4 w-4" />
+      </button>
+      {open && (
+        <div role="menu" data-testid="chat-add-menu" className={`${PANEL} bottom-full left-0 mb-2`}>
+          <Row
+            icon={<Paperclip className="h-4 w-4" />}
+            label={t("chat.upload")}
+            testId="chat-add-upload"
+            onHover={() => setSub(null)}
+            onClick={() => {
+              close();
+              onUpload();
+            }}
+          />
+          <Row
+            icon={<FolderOpen className="h-4 w-4" />}
+            label={t("chat.projectFiles")}
+            more
+            active={sub === "project"}
+            testId="chat-add-project"
+            onHover={() => setSub("project")}
+            onClick={() => setSub(sub === "project" ? null : "project")}
+          />
+          {laneId !== null && (
+            <Row
+              icon={<FileText className="h-4 w-4" />}
+              label={t("chat.contextFiles")}
+              more
+              active={sub === "context"}
+              testId="chat-add-context"
+              onHover={() => setSub("context")}
+              onClick={() => setSub(sub === "context" ? null : "context")}
+            />
+          )}
+          <Row
+            icon={<History className="h-4 w-4" />}
+            label={t("chat.recentUploads")}
+            more
+            active={sub === "recent"}
+            testId="chat-add-recent"
+            onHover={() => setSub("recent")}
+            onClick={() => setSub(sub === "recent" ? null : "recent")}
+          />
+          {skills && (
+            <>
+              <Row
+                icon={<ScrollText className="h-4 w-4" />}
+                label={t("chat.skills")}
+                more
+                active={sub === "skills"}
+                testId="chat-add-skills"
+                onHover={() => setSub("skills")}
+                onClick={() => setSub(sub === "skills" ? null : "skills")}
+              />
+              <Row
+                icon={<Plug className="h-4 w-4" />}
+                label={t("chat.plugins")}
+                more
+                active={sub === "plugins"}
+                testId="chat-add-plugins"
+                onHover={() => setSub("plugins")}
+                onClick={() => setSub(sub === "plugins" ? null : "plugins")}
+              />
+            </>
+          )}
+
+          {sub === "project" && (
+            <div role="menu" className={`${PANEL} bottom-0 left-full ml-1 w-72 pt-2`}>
+              <ProjectFiles cwd={cwd} onPick={(rel) => attach(projectAttachment(rel))} />
+            </div>
+          )}
+
+          {(sub === "context" || sub === "recent") && (
+            <div role="menu" className={`${PANEL} bottom-0 left-full ml-1`}>
+              <div className="max-h-72 overflow-y-auto">
+                {(sub === "context" ? context : recent)?.length ? (
+                  (sub === "context" ? context! : recent).map((it) => (
+                    <Row
+                      key={it.path}
+                      icon={<FileText className="h-4 w-4" />}
+                      label={it.name}
+                      title={it.path.replace(/^@/, "")}
+                      testId={`chat-add-${sub}-${it.name}`}
+                      onClick={() => attach(it)}
+                    />
+                  ))
+                ) : (
+                  <p className="px-3 py-1.5 text-xs text-fg-muted">
+                    {sub === "context" && !context ? "…" : t("chat.none")}
+                  </p>
+                )}
+              </div>
+            </div>
+          )}
+
+          {sub === "skills" && (
+            <div role="menu" className={`${PANEL} bottom-0 left-full ml-1`}>
+              <div className="max-h-72 overflow-y-auto">{entries(lists?.skills ?? [], "")}</div>
+              <div className="my-1 border-t border-border" />
+              <Row
+                icon={<Settings2 className="h-4 w-4" />}
+                label={t("chat.manageSkills")}
+                onClick={() => manage("skills")}
+              />
+            </div>
+          )}
+
+          {sub === "plugins" && (
+            <div role="menu" className={`${PANEL} bottom-0 left-full ml-1`}>
+              <div className="max-h-72 overflow-y-auto">
+                {lists && lists.plugins.length === 0 && (
+                  <p className="px-3 py-1.5 text-xs text-fg-muted">{t("chat.none")}</p>
+                )}
+                {!lists && <p className="px-3 py-1.5 text-xs text-fg-muted">…</p>}
+                {lists?.plugins.map((p) => (
+                  <Row
+                    key={p.name}
+                    icon={<Plug className="h-4 w-4" />}
+                    label={p.name}
+                    more
+                    active={plugin === p.name}
+                    testId={`chat-add-plugin-${p.name}`}
+                    onHover={() => setPlugin(p.name)}
+                    onClick={() => setPlugin(plugin === p.name ? null : p.name)}
+                  />
+                ))}
+              </div>
+              <div className="my-1 border-t border-border" />
+              <Row
+                icon={<Settings2 className="h-4 w-4" />}
+                label={t("chat.managePlugins")}
+                onClick={() => manage("plugins")}
+              />
+              {shownPlugin && (
+                <div role="menu" className={`${PANEL} bottom-0 left-full ml-1`}>
+                  <div className="max-h-72 overflow-y-auto">
+                    {entries(
+                      shownPlugin.items,
+                      `${shownPlugin.name}:`,
+                      t("chat.fromPlugin", { name: shownPlugin.name })
+                    )}
+                  </div>
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

client/src/components/run/ChatFilePreview.tsx

@@ -0,0 +1,371 @@
+/**
+ * @file ChatFilePreview.tsx
+ * @description A file a Chat pane's session touched, shown the way Claude
+ * Desktop shows one: `FilePreview` (name · EXT, Copy path, Close, then the
+ * content) and `FileListModal` (a list on the left, the picked file's preview
+ * on the right — Claude's Uploads dialog). Content comes only through routes
+ * that already guard it: a file inside the workspace through
+ * `GET /api/lanes/:id/git/file` (or `/git/raw` for an image), a file under
+ * `~/.claude` (a memory file, a plugin's skill) through `GET /api/cc-config/file`,
+ * an attached image or text file through `GET /api/run/drop/:name`, an image
+ * the session read anywhere else through `GET /api/sessions/:id/image`, and a
+ * text file it read, wrote or named (a generated report) anywhere else through
+ * `GET /api/sessions/:id/file`.
+ * Anything else (or a file those routes refuse) shows its path only. A Windows path's `\` counts as `/` throughout.
+ * `SkillListModal` is the same dialog over the session's skills, each one's
+ * SKILL.md found by name (`plugin:name` from the plugin list, else the user's
+ * or the project's); a built-in skill has no file and shows by name only.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useRef, useState, type DragEvent } from "react";
+import { createPortal } from "react-dom";
+import { useTranslation } from "react-i18next";
+import { Copy, FileText, Loader2, X } from "lucide-react";
+import { api, gitTarget } from "../../lib/api";
+import { copyText } from "../../lib/clipboard";
+import { useDialog } from "../../hooks/useDialog";
+import { dragSkill } from "../../lib/promptAttach";
+import { MarkdownPreview, isMarkdown } from "../MarkdownPreview";
+
+/** Where a Chat pane's files can be read from. */
+export interface PreviewScope {
+  laneId: number | null;
+  /** The workspace's own folder. */
+  laneCwd: string;
+  /** The pane's folder — the workspace's, or the session's own worktree. */
+  cwd: string;
+  sessionId: string;
+}
+
+const IMAGE_RE = /\.(png|jpe?g|gif|webp)$/i;
+// An attached file the drop route serves as text (`DROP_TEXT_TYPES` in server/routes/run.js).
+const DROP_TEXT_RE = /\.(txt|md|markdown|csv|tsv|log|json|xml|ya?ml)$/i;
+// The drop dir (`<data dir>/drops/`), or the older `<tmp>/agenthub-drops-<uid>/`.
+const DROP_RE =
+  /[\\/](?:agenthub-drops-\d+|drops)[\\/]([0-9a-f]{16}(?:-[A-Za-z0-9._-]+)?\.[A-Za-z0-9]+)$/;
+/** A dropped text file shown at most this long. */
+const DROP_TEXT_MAX = 200_000;
+
+/** `C:\a\b` → `C:/a/b`: a Windows path matched like a POSIX one. */
+const slashed = (p: string) => p.replace(/\\/g, "/");
+export const baseName = (p: string) => p.split(/[\\/]/).pop() || p;
+/** `report.v2.xlsx` → `XLSX`; none → "". */
+export const extOf = (p: string) => {
+  const m = /\.([A-Za-z0-9]+)$/.exec(baseName(p));
+  return m ? m[1]!.toUpperCase() : "";
+};
+/** An attached file's name without the drop dir's random prefix. */
+export const displayName = (p: string) =>
+  DROP_RE.test(p) ? baseName(p).replace(/^[0-9a-f]{16}-?/, "") || baseName(p) : baseName(p);
+
+type Content =
+  | { kind: "loading" }
+  | { kind: "image"; src: string }
+  | { kind: "text"; text: string; truncated: boolean }
+  | { kind: "none" };
+
+function useContent(path: string, scope: PreviewScope): Content {
+  const [content, setContent] = useState<Content>({ kind: "loading" });
+  useEffect(() => {
+    let live = true;
+    const show = (p: Promise<Content>) => {
+      setContent({ kind: "loading" });
+      p.then((c) => live && setContent(c)).catch(() => live && setContent({ kind: "none" }));
+    };
+    const drop = DROP_RE.exec(path);
+    if (drop) {
+      const src = `/api/run/drop/${encodeURIComponent(drop[1]!)}`;
+      if (IMAGE_RE.test(path)) setContent({ kind: "image", src });
+      else if (DROP_TEXT_RE.test(path))
+        show(
+          fetch(src).then(async (r) => {
+            if (!r.ok) throw new Error(String(r.status));
+            const text = await r.text();
+            return {
+              kind: "text",
+              text: text.slice(0, DROP_TEXT_MAX),
+              truncated: text.length > DROP_TEXT_MAX,
+            };
+          })
+        );
+      else setContent({ kind: "none" });
+      return () => {
+        live = false;
+      };
+    }
+    const file = slashed(path);
+    const base = slashed(scope.cwd).replace(/\/+$/, "");
+    if (scope.laneId === null || !base || !file.startsWith(`${base}/`)) {
+      // Claude Code's own files (memory, a skill): the config pages' guarded read.
+      if (/\/\.claude\//.test(file) && !IMAGE_RE.test(file)) {
+        show(
+          api.ccConfig
+            .file(path)
+            .then((f) => ({ kind: "text", text: f.text, truncated: !!f.truncated }))
+        );
+      } else if (IMAGE_RE.test(file) && scope.sessionId) {
+        // An image it read elsewhere (a screenshot under ~/.cache): served
+        // only because this session's own Read named it.
+        setContent({ kind: "image", src: api.sessions.readImageUrl(scope.sessionId, path) });
+      } else if (scope.sessionId && /^(?:\/|[A-Za-z]:\/)/.test(file)) {
+        // A text file it read or wrote elsewhere (a report under ~/Documents):
+        // served only because this session's own Read/Write/Edit named it.
+        show(
+          api.sessions
+            .readFile(scope.sessionId, path)
+            .then((f) => ({ kind: "text", text: f.text, truncated: f.truncated }))
+        );
+      } else setContent({ kind: "none" });
+      return () => {
+        live = false;
+      };
+    }
+    const rel = file.slice(base.length + 1);
+    const target =
+      base === slashed(scope.laneCwd).replace(/\/+$/, "")
+        ? scope.laneId
+        : gitTarget(scope.laneId, scope.sessionId);
+    if (IMAGE_RE.test(path)) {
+      setContent({ kind: "image", src: api.lanes.gitRawUrl(target, rel) });
+      return;
+    }
+    show(
+      api.lanes
+        .gitFile(target, rel)
+        .then((f) =>
+          f.available && !f.binary
+            ? { kind: "text", text: f.lines.join("\n"), truncated: f.truncated }
+            : { kind: "none" }
+        )
+    );
+    return () => {
+      live = false;
+    };
+  }, [path, scope.cwd, scope.laneCwd, scope.laneId, scope.sessionId]);
+  return content;
+}
+
+function Body({ path, scope }: { path: string; scope: PreviewScope }) {
+  const { t } = useTranslation("run");
+  const loaded = useContent(path, scope);
+  // An image the route refused (gone, server mode) shows like no preview.
+  const [broken, setBroken] = useState<string | null>(null);
+  const content: Content =
+    loaded.kind === "image" && loaded.src === broken ? { kind: "none" } : loaded;
+  if (content.kind === "loading") {
+    return (
+      <div className="flex flex-1 items-center justify-center">
+        <Loader2 className="h-5 w-5 animate-spin text-fg-muted" />
+      </div>
+    );
+  }
+  if (content.kind === "image") {
+    return (
+      <div className="flex flex-1 items-center justify-center overflow-auto p-4">
+        <img
+          src={content.src}
+          alt={baseName(path)}
+          onError={() => setBroken(content.src)}
+          className="max-h-full max-w-full object-contain"
+        />
+      </div>
+    );
+  }
+  if (content.kind === "none") {
+    return (
+      <div className="flex flex-1 flex-col items-center justify-center gap-2 p-6 text-center text-sm text-fg-muted">
+        <FileText className="h-8 w-8" />
+        <p>{t("chat.outline.noPreview")}</p>
+        <p className="break-all font-mono text-xs">{path}</p>
+      </div>
+    );
+  }
+  return (
+    <div className="min-h-0 flex-1 overflow-auto">
+      {isMarkdown(path) ? (
+        <MarkdownPreview text={content.text} className="p-4" />
+      ) : (
+        <pre className="p-4 font-mono text-xs leading-relaxed text-fg-secondary">
+          {content.text}
+        </pre>
+      )}
+      {content.truncated && (
+        <p className="px-4 pb-4 text-xs text-fg-muted">{t("chat.outline.truncated")}</p>
+      )}
+    </div>
+  );
+}
+
+/** One file: header (name · EXT, Copy path, Close) over its content. */
+export function FilePreview({
+  path,
+  scope,
+  onClose,
+  className = "",
+}: {
+  path: string;
+  scope: PreviewScope;
+  onClose: () => void;
+  className?: string;
+}) {
+  const { t } = useTranslation("run");
+  return (
+    <section
+      data-testid="chat-file-preview"
+      className={`flex min-h-0 min-w-0 flex-col overflow-hidden bg-surface-1 ${className}`}
+    >
+      <header className="flex items-center gap-2 border-b border-border px-4 py-2.5">
+        <span className="min-w-0 truncate text-sm text-fg-primary" title={path}>
+          {displayName(path).replace(/\.[A-Za-z0-9]+$/, "")}
+        </span>
+        <span className="text-xs text-fg-muted">{extOf(path)}</span>
+        <div className="ml-auto flex items-center gap-1">
+          <button
+            type="button"
+            onClick={() => void copyText(path)}
+            title={t("chat.outline.copyPath", { path })}
+            aria-label={t("chat.outline.copyPath", { path })}
+            className="flex h-7 w-7 items-center justify-center rounded text-fg-muted hover:bg-surface-3 hover:text-fg-primary"
+          >
+            <Copy className="h-3.5 w-3.5" />
+          </button>
+          <button
+            type="button"
+            onClick={onClose}
+            title={t("chat.outline.close")}
+            aria-label={t("chat.outline.close")}
+            className="flex h-7 w-7 items-center justify-center rounded text-fg-muted hover:bg-surface-3 hover:text-fg-primary"
+          >
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+      </header>
+      <Body path={path} scope={scope} />
+    </section>
+  );
+}
+
+/** Claude's Uploads dialog: the files on the left, the picked one on the right. */
+export function FileListModal({
+  title,
+  paths,
+  label = displayName,
+  scope,
+  onClose,
+  onDragItem,
+}: {
+  title: string;
+  paths: string[];
+  /** A row's text; the file name by default. */
+  label?: (path: string) => string;
+  scope: PreviewScope;
+  onClose: () => void;
+  /** Rows drag into the prompt box; the dialog then closes, out of the way. */
+  onDragItem?: (e: DragEvent, path: string) => void;
+}) {
+  const [picked, setPicked] = useState(paths[0] ?? "");
+  const panelRef = useRef<HTMLDivElement>(null);
+  useDialog(true, panelRef, onClose);
+  // Into document.body, like ImageLightbox: a pane's own stacking layer
+  // would otherwise draw over a `fixed` overlay opened from inside it.
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[200] flex items-center justify-center bg-surface-0/70 p-6"
+      onClick={onClose}
+    >
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={title}
+        data-testid="chat-file-modal"
+        onClick={(e) => e.stopPropagation()}
+        className="flex h-[80vh] w-full max-w-6xl overflow-hidden rounded-xl border border-border bg-surface-1 shadow-2xl"
+      >
+        <div className="flex w-80 flex-shrink-0 flex-col border-r border-border">
+          <h2 className="px-5 pb-3 pt-5 text-lg text-fg-primary">{title}</h2>
+          <ul className="min-h-0 flex-1 space-y-0.5 overflow-y-auto px-2 pb-3">
+            {paths.map((p) => (
+              <li key={p}>
+                <button
+                  type="button"
+                  onClick={() => setPicked(p)}
+                  draggable={!!onDragItem}
+                  onDragStart={(e) => {
+                    onDragItem?.(e, p);
+                    // Not in dragstart itself: removing the source there cancels the drag.
+                    if (onDragItem) window.setTimeout(onClose, 0);
+                  }}
+                  title={p}
+                  aria-current={p === picked}
+                  className={`flex w-full items-center gap-2 rounded-lg px-3 py-2 text-left text-sm ${p === picked ? "bg-surface-3 text-fg-primary" : "text-fg-secondary hover:bg-surface-2"}`}
+                >
+                  <FileText className="h-4 w-4 flex-shrink-0 text-fg-muted" />
+                  <span className="min-w-0 truncate">{label(p)}</span>
+                </button>
+              </li>
+            ))}
+          </ul>
+        </div>
+        {picked && <FilePreview path={picked} scope={scope} onClose={onClose} className="flex-1" />}
+      </div>
+    </div>,
+    document.body
+  );
+}
+
+/** The session's skills in the list dialog, each one's SKILL.md previewed. */
+export function SkillListModal({
+  title,
+  names,
+  scope,
+  onClose,
+  draggable = false,
+}: {
+  title: string;
+  names: string[];
+  scope: PreviewScope;
+  onClose: () => void;
+  /** Rows drag into the prompt box as `/name`. */
+  draggable?: boolean;
+}) {
+  const [files, setFiles] = useState<Map<string, string> | null>(null);
+  useEffect(() => {
+    let live = true;
+    void Promise.all([
+      api.ccConfig.skills(undefined, scope.cwd).catch(() => ({ items: [] })),
+      api.ccConfig.plugins().catch(() => ({ plugins: [] })),
+    ]).then(([sk, pl]) => {
+      const found = new Map<string, string>();
+      const add = (name: string, file: string | undefined) => {
+        if (file && !found.has(name)) found.set(name, file);
+      };
+      for (const p of pl.plugins) {
+        const items = p.contributes?.items;
+        for (const it of [...(items?.skills ?? []), ...(items?.commands ?? [])])
+          add(`${p.name}:${it.name}`, it.file);
+      }
+      // A personal skill wins over a project one of the same name, as in Claude Code.
+      for (const s of sk.items) if (s.scope === "user") add(s.name, s.file);
+      for (const s of sk.items) add(s.name, s.file);
+      if (live) setFiles(found);
+    });
+    return () => {
+      live = false;
+    };
+  }, [scope.cwd]);
+  if (!files) return null;
+  // A built-in skill has no file: its name stands in and previews as nothing.
+  const byPath = new Map(names.map((n) => [files.get(n) ?? n, n]));
+  return (
+    <FileListModal
+      title={title}
+      paths={[...byPath.keys()]}
+      label={(p) => byPath.get(p) ?? displayName(p)}
+      scope={scope}
+      onClose={onClose}
+      onDragItem={draggable ? (e, p) => dragSkill(e, byPath.get(p) ?? p) : undefined}
+    />
+  );
+}

client/src/components/run/ChatOutline.tsx

@@ -0,0 +1,382 @@
+/**
+ * @file ChatOutline.tsx
+ * @description The right-hand panel of a Chat pane, laid out like
+ * Claude Desktop's activity panel: the session's Progress (its
+ * TaskCreate/TaskUpdate or TodoWrite plan, only when it has one — how many
+ * steps are done of how many, a bar, and the step in progress highlighted), the Outputs
+ * it wrote or edited (name + EXT tag; a click previews the file), and "Used in
+ * this session" — the files attached to its prompts, the files it read and the
+ * memory files it used and its skills (a click opens the list with a
+ * preview — a skill's SKILL.md), and its MCP servers (a click opens the
+ * Claude config page). Every row but MCP drags into the prompt box: a file
+ * as an attachment, a group as all of its files, a lone skill as `/name`.
+ * Read from
+ * `GET /api/sessions/:id/outline` by `useSessionOutline`, which the pane also
+ * uses for the collapsed button's count.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import {
+  useEffect,
+  useState,
+  type ComponentType,
+  type DragEvent,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import { useTranslation } from "react-i18next";
+import { Link } from "react-router-dom";
+import { useSettingsHref } from "../../lib/settingsLink";
+import {
+  BookOpen,
+  Check,
+  ChevronDown,
+  FileCode,
+  FileImage,
+  FileSearch,
+  FileSpreadsheet,
+  FileText,
+  History,
+  Paperclip,
+  Plug,
+  X,
+} from "lucide-react";
+import { api, type SessionOutline } from "../../lib/api";
+import { keepIfSame } from "../../lib/keepIfSame";
+import { isShown } from "../../hooks/useOnScreen";
+import { displayName, extOf } from "./ChatFilePreview";
+import { dragAttachments, dragSkill, type Attachment } from "../../lib/promptAttach";
+
+const POLL_MS = 5000;
+const EMPTY: SessionOutline = {
+  progress: [],
+  outputs: [],
+  files: [],
+  uploads: [],
+  memory: [],
+  skills: [],
+  mcp: [],
+};
+
+/** The session's outline, re-read on a visibility-gated poll — skipped too
+ *  while `onScreen` says the pane is hidden (another workspace or tab, kept
+ *  mounted). An unchanged answer keeps the old object: no re-render. */
+export function useSessionOutline(
+  sessionId: string,
+  onScreen?: RefObject<boolean>
+): SessionOutline {
+  const [outline, setOutline] = useState<SessionOutline>(EMPTY);
+  useEffect(() => {
+    let live = true;
+    const load = () =>
+      api.sessions
+        .outline(sessionId)
+        .then((o) => live && setOutline(keepIfSame<SessionOutline>({ ...EMPTY, ...o })))
+        .catch(() => {});
+    void load();
+    const timer = window.setInterval(() => {
+      if (onScreen ? isShown(onScreen) : document.visibilityState === "visible") void load();
+    }, POLL_MS);
+    return () => {
+      live = false;
+      window.clearInterval(timer);
+    };
+  }, [sessionId, onScreen]);
+  return outline;
+}
+
+export type OutlineList = "uploads" | "files" | "memory" | "skills";
+
+/** A listed file as a prompt attachment: an upload by its bare path, as the
+ *  composer attaches one; anything else as an `@` mention. */
+export function outlineAttachment(path: string, upload = false): Attachment {
+  return { path: upload ? path : `@${path}`, name: displayName(path) };
+}
+
+const dragFiles =
+  (paths: string[], upload = false) =>
+  (e: DragEvent) =>
+    dragAttachments(
+      e,
+      paths.map((p) => outlineAttachment(p, upload))
+    );
+
+function fileIcon(path: string) {
+  const ext = extOf(path).toLowerCase();
+  if (["xlsx", "xls", "csv", "tsv"].includes(ext)) return FileSpreadsheet;
+  if (["png", "jpg", "jpeg", "gif", "webp", "svg"].includes(ext)) return FileImage;
+  if (
+    /^(c|cc|cpp|cs|css|go|h|html|java|js|jsx|json|kt|mjs|cjs|php|py|rb|rs|sh|sql|swift|ts|tsx|vue|ya?ml|toml)$/.test(
+      ext
+    )
+  )
+    return FileCode;
+  return FileText;
+}
+
+function Section({
+  title,
+  count,
+  action,
+  grow,
+  children,
+}: {
+  title: string;
+  /** Beside the title: a count, or a "3/7". */
+  count?: number | string;
+  action?: ReactNode;
+  /** Takes the panel's free height and scrolls inside it. */
+  grow?: boolean;
+  children: ReactNode;
+}) {
+  const [open, setOpen] = useState(true);
+  return (
+    <section className={`flex flex-col px-3 pt-3 ${grow && open ? "min-h-0 flex-1" : ""}`}>
+      <div className="flex items-center gap-1.5 px-1 pb-1">
+        <button
+          type="button"
+          onClick={() => setOpen((o) => !o)}
+          aria-expanded={open}
+          className="flex items-center gap-1.5 text-sm font-medium text-fg-primary"
+        >
+          {title}
+          {count ? <span className="text-xs font-normal text-fg-muted">{count}</span> : null}
+          <ChevronDown
+            className={`h-3.5 w-3.5 text-fg-muted transition-transform ${open ? "" : "-rotate-90"}`}
+          />
+        </button>
+        <div className="ml-auto flex items-center">{action}</div>
+      </div>
+      {open && (
+        <div
+          className={
+            grow
+              ? "min-h-0 flex-1 overflow-y-auto [mask-image:linear-gradient(to_bottom,transparent,black_8px,black_calc(100%-8px),transparent)]"
+              : ""
+          }
+        >
+          {children}
+        </div>
+      )}
+    </section>
+  );
+}
+
+const rowClass =
+  "flex w-full items-center gap-2 rounded-md px-1.5 py-1.5 text-left text-[13px] text-fg-secondary enabled:hover:bg-surface-3";
+
+/** A "Used in this session" row: icon, label, the first names, +N. */
+function UsedRow({
+  icon: Icon,
+  label,
+  names,
+  onClick,
+  onDragStart,
+  to,
+}: {
+  icon: ComponentType<{ className?: string }>;
+  label: string;
+  names: string[];
+  onClick?: () => void;
+  /** The row drags into the prompt box. */
+  onDragStart?: (e: DragEvent) => void;
+  to?: string;
+}) {
+  const shown = names.slice(0, 2).join(", ");
+  const inner = (
+    <>
+      <Icon className="h-4 w-4 flex-shrink-0 text-fg-muted" />
+      <span className="flex-shrink-0 text-fg-primary">{label}</span>
+      <span className="min-w-0 flex-1 truncate text-xs text-fg-muted">{shown}</span>
+      {names.length > 2 && (
+        <span className="flex-shrink-0 text-xs text-fg-muted">+{names.length - 2}</span>
+      )}
+    </>
+  );
+  const title = `${label}: ${names.join(", ")}`;
+  return to ? (
+    <Link to={to} title={title} className={`${rowClass} hover:bg-surface-3`}>
+      {inner}
+    </Link>
+  ) : (
+    <button
+      type="button"
+      title={title}
+      onClick={onClick}
+      draggable={!!onDragStart}
+      onDragStart={onDragStart}
+      className={rowClass}
+    >
+      {inner}
+    </button>
+  );
+}
+
+const stem = (p: string) => displayName(p).replace(/\.[A-Za-z0-9]+$/, "");
+
+export function ChatOutline({
+  outline: o,
+  onClose,
+  onOpenFile,
+  onOpenList,
+}: {
+  outline: SessionOutline;
+  onClose: () => void;
+  onOpenFile: (path: string) => void;
+  onOpenList: (list: OutlineList) => void;
+}) {
+  const { t } = useTranslation("run");
+  const href = useSettingsHref();
+  const doneSteps = o.progress.filter((p) => p.status === "completed").length;
+  const used = o.uploads.length + o.files.length + o.memory.length + o.skills.length + o.mcp.length;
+  const close = (
+    <button
+      type="button"
+      onClick={onClose}
+      title={t("chat.outline.hide")}
+      aria-label={t("chat.outline.hide")}
+      className="flex h-6 w-6 items-center justify-center rounded text-fg-muted hover:bg-surface-3 hover:text-fg-primary"
+    >
+      <X className="h-4 w-4" />
+    </button>
+  );
+
+  return (
+    <aside
+      data-testid="chat-outline"
+      aria-label={t("chat.outline.panel")}
+      // Over the conversation in a narrow pane (the container is PaneChat's
+      // root; `--chat-area` keeps the prompt box below it uncovered),
+      // beside it once the pane has room, as wide as PaneChat's splitter says.
+      className="absolute right-3 top-3 bottom-[calc(100%-var(--chat-area,100%)+0.75rem)] z-30 flex w-[clamp(15rem,34%,20rem)] max-w-[calc(100%-1.5rem)] flex-shrink-0 flex-col overflow-hidden rounded-xl border border-border bg-surface-1 pb-2 shadow-xl [@container(min-width:40rem)]:static [@container(min-width:40rem)]:m-3 [@container(min-width:40rem)]:ml-0 [@container(min-width:40rem)]:w-[calc(var(--chat-side)-0.75rem)] [@container(min-width:40rem)]:max-w-none [@container(min-width:40rem)]:shadow-none"
+    >
+      {o.progress.length > 0 && (
+        <Section
+          title={t("chat.outline.progress")}
+          count={`${doneSteps}/${o.progress.length}`}
+          action={close}
+        >
+          <div
+            role="progressbar"
+            aria-valuemin={0}
+            aria-valuemax={o.progress.length}
+            aria-valuenow={doneSteps}
+            aria-label={t("chat.outline.progress")}
+            className="mx-1.5 mb-1.5 h-1 overflow-hidden rounded-full bg-surface-3"
+          >
+            <div
+              className="h-full rounded-full bg-accent-solid transition-[width] duration-500"
+              style={{ width: `${(doneSteps / o.progress.length) * 100}%` }}
+            />
+          </div>
+          {o.progress.map((task) => {
+            const done = task.status === "completed";
+            const now = task.status === "in_progress";
+            return (
+              <div
+                key={task.id}
+                className={`${rowClass} ${now ? "bg-accent/10 font-medium" : ""}`}
+                title={task.subject}
+                aria-current={now ? "step" : undefined}
+              >
+                {done ? (
+                  <span className="flex h-4 w-4 flex-shrink-0 items-center justify-center rounded-full bg-accent-solid text-white">
+                    <Check className="h-3 w-3" />
+                  </span>
+                ) : (
+                  <span
+                    className={`h-4 w-4 flex-shrink-0 rounded-full border-2 ${task.status === "in_progress" ? "animate-pulse-dot border-accent" : "border-border"}`}
+                  />
+                )}
+                <span
+                  className={`min-w-0 flex-1 truncate ${done ? "text-fg-muted line-through" : task.status === "in_progress" ? "text-fg-primary" : ""}`}
+                >
+                  {task.subject}
+                </span>
+              </div>
+            );
+          })}
+        </Section>
+      )}
+      <Section
+        title={t("chat.outline.outputs")}
+        count={o.outputs.length}
+        action={o.progress.length ? undefined : close}
+        grow
+      >
+        {o.outputs.length ? (
+          o.outputs.map((p) => {
+            const Icon = fileIcon(p);
+            return (
+              <button
+                key={p}
+                type="button"
+                title={p}
+                aria-label={`${extOf(p)}: ${stem(p)}`}
+                onClick={() => onOpenFile(p)}
+                draggable
+                onDragStart={dragFiles([p])}
+                className={rowClass}
+              >
+                <Icon className="h-4 w-4 flex-shrink-0 text-fg-muted" />
+                <span className="min-w-0 flex-1 truncate">{stem(p)}</span>
+                <span className="flex-shrink-0 text-[11px] text-fg-muted">{extOf(p)}</span>
+              </button>
+            );
+          })
+        ) : (
+          <p className="px-1.5 py-1 text-xs text-fg-muted">{t("chat.outline.empty")}</p>
+        )}
+      </Section>
+      {used > 0 && (
+        <Section title={t("chat.outline.used")}>
+          {o.uploads.length > 0 && (
+            <UsedRow
+              icon={Paperclip}
+              label={t("chat.outline.uploads")}
+              names={o.uploads.map(displayName)}
+              onClick={() => onOpenList("uploads")}
+              onDragStart={dragFiles(o.uploads, true)}
+            />
+          )}
+          {o.files.length > 0 && (
+            <UsedRow
+              icon={FileSearch}
+              label={t("chat.outline.files")}
+              names={o.files.map(displayName)}
+              onClick={() => onOpenList("files")}
+              onDragStart={dragFiles(o.files)}
+            />
+          )}
+          {o.memory.length > 0 && (
+            <UsedRow
+              icon={History}
+              label={t("chat.outline.memory")}
+              names={o.memory.map(stem)}
+              onClick={() => onOpenList("memory")}
+              onDragStart={dragFiles(o.memory)}
+            />
+          )}
+          {o.skills.length > 0 && (
+            <UsedRow
+              icon={BookOpen}
+              label={t("chat.skills")}
+              names={o.skills}
+              onClick={() => onOpenList("skills")}
+              // One command per prompt: several are dragged one by one from the list.
+              onDragStart={o.skills.length === 1 ? (e) => dragSkill(e, o.skills[0]!) : undefined}
+            />
+          )}
+          {o.mcp.length > 0 && (
+            <UsedRow
+              icon={Plug}
+              label={t("chat.outline.connectors")}
+              names={o.mcp}
+              to={href("agents/claude-code?tab=mcp")}
+            />
+          )}
+        </Section>
+      )}
+    </aside>
+  );
+}

client/src/components/run/ConsoleTabs.tsx

@@ -8,8 +8,11 @@
  * prompt it started on, else its tool and number; a combo tab shows every
  * pane's icon and name. A tab carries a state dot (waiting for you / error /
  * running — a combo shows the most urgent, with screen-reader text). A tab's
- * X stops every session in it (`DELETE /api/run/:id`) — after a confirm when
- * one is an AI tool, since it may be mid-turn; a shell closes at once. Arrow
+ * X stops every session in it AND archives them (`endRuns`,
+ * `DELETE /api/run/:id?archive=1`); the moon beside it (and the tab menu's
+ * Sleep) stops its AI sessions but keeps them listed, to resume later. Either
+ * asks first when one is an AI tool, since it may be mid-turn; a shell closes
+ * at once. Arrow
  * keys, Home and End move between tabs (one tab stop, APG). Errors are
  * toasts. The `+` menu opens a new tab in the free slot the server picks
  * (`slot: "auto"`) — a plain shell (`POST /api/lanes/:id/start {shell: true}`)
@@ -25,8 +28,15 @@
  * bar takes that pane out into a tab of its own there. Dropped on the MIDDLE
  * of another tab, a tab (or a pane header) joins that tab instead
  * (`joinGroup`: side by side, then under the right pane, then under the left
- * one, up to four panes). A right-click on a tab
- * opens the same actions as a menu (`ContextMenu`).
+ * one, up to four panes). A pane drag held over another tab for `SPRING_MS` shows that tab
+ * (spring-loaded, as a file manager's folder), so the pane can be dropped on
+ * any of its panes' edges; near either end of an overflowing bar a drag
+ * scrolls it. A right-click on a tab
+ * opens the same actions as a menu (`ContextMenu`). With tabs from every
+ * workspace on, `tabs` spans every workspace (each run's `slot` a `paneKey`)
+ * and `workspaceOf` names each tab's workspace before its own name. Settings
+ * opened on a workspace is one more tab at the bar's end (`settings`, kept
+ * until its X), shown instead of the panes while it is the active one.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
@@ -41,18 +51,26 @@ import {
 } from "react";
 import { useTranslation } from "react-i18next";
 import { useNavigate } from "react-router-dom";
-import { House, Plus, Settings2, SquareTerminal, X } from "lucide-react";
+import { House, Moon, Plus, Settings, Settings2, SquareTerminal, X } from "lucide-react";
 import { api } from "../../lib/api";
+import { useSettingsHref } from "../../lib/settingsLink";
 import type { RunHandle } from "../../lib/api";
 import { isSessionAwaitingInput, type Lane, type Session } from "../../lib/types";
 import { toast } from "../../lib/toast";
-import { confirmDialog } from "../../lib/confirm";
+import { canSleep, endRuns } from "../../lib/stopSession";
 import { copyText } from "../../lib/clipboard";
 import { isSubmitEnter } from "../../lib/keys";
 import { useAiTools } from "../../hooks/useAiTools";
 import { AiToolIcon } from "../AiToolIcon";
 import { freeSlot, startInFreeTab } from "../lanes/startSession";
-import { PANE_DRAG_TYPE, RunIcon, startPaneDrag, type GroupsUpdate } from "./PaneGrid";
+import {
+  PANE_DRAG_TYPE,
+  RunIcon,
+  paneDragSlot,
+  setDragChip,
+  startPaneDrag,
+  type GroupsUpdate,
+} from "./PaneGrid";
 import { insertionIndex } from "../../lib/laneOrderStorage";
 import {
   type PaneGroups,
@@ -62,6 +80,7 @@ import {
   joinGroup,
   leaves,
   reorderGroups,
+  slotOfKey,
 } from "../../lib/paneLayout";
 import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "../ContextMenu";
 
@@ -77,7 +96,7 @@ export function runName(
 ): string {
   if (r.tool === "shell") return terminal;
   const prompt = r.promptPreview?.trim().split("\n")[0];
-  return session?.name || prompt || `${toolLabel} #${(r.slot ?? 0) + 1}`;
+  return session?.name || prompt || `${toolLabel} #${slotOfKey(r.slot ?? 0) + 1}`;
 }
 
 export type RunState = "awaiting" | "error" | "running";
@@ -149,6 +168,14 @@ interface Tab {
 
 const URGENCY: RunState[] = ["awaiting", "error", "running"];
 
+/** How long a pane drag rests on a tab before that tab is shown. */
+export const SPRING_MS = 600;
+/** Within this many px of an overflowing bar's end, a drag scrolls it. */
+const EDGE_SCROLL_PX = 40;
+
+/** The Settings tab's key among the tabs' (a group's key is its slots). */
+const SETTINGS_KEY = "settings";
+
 export function ConsoleTabs({
   lane,
   tabs: runs,
@@ -160,10 +187,14 @@ export function ConsoleTabs({
   actions,
   sessions,
   onRenamed,
+  workspaceOf,
+  settings,
 }: {
   lane: Lane;
   /** The workspace's live runs, in slot order. */
   tabs: RunHandle[];
+  /** Tabs from every workspace: the name of the workspace a run belongs to. */
+  workspaceOf?: (r: RunHandle) => string;
   /** The tabs: groups of panes, the active one on screen. */
   groups: PaneGroups;
   /** Reorders the tabs or takes a pane out into a tab of its own. */
@@ -181,9 +212,12 @@ export function ConsoleTabs({
   onHome?: () => void;
   /** Right end of the bar (the single pane's split menus). */
   actions?: ReactNode;
+  /** The Settings tab, while it is open: on screen (`active`), shown, closed. */
+  settings?: { active: boolean; onOpen: () => void; onClose: () => void } | null;
 }) {
   const { t } = useTranslation("lanes");
   const navigate = useNavigate();
+  const settingsHref = useSettingsHref();
   const aiTools = useAiTools();
   const [menuOpen, setMenuOpen] = useState(false);
   // The tab being renamed (its run id) and the draft name.
@@ -240,8 +274,59 @@ export function ConsoleTabs({
     if (!tab || dragged.current.some((s) => tab.slots.includes(s))) return null;
     return tab.slots.length + Math.max(dragged.current.length, 1) <= MAX_PANES ? i : null;
   };
+  // A pane drag resting on a tab (its drawn index) shows it after SPRING_MS.
+  const spring = useRef<{ at: number; timer: ReturnType<typeof setTimeout> } | null>(null);
+  const stopSpring = () => {
+    if (spring.current) clearTimeout(spring.current.timer);
+    spring.current = null;
+  };
+  useEffect(() => stopSpring, []);
+  const hoveredIndexAt = (x: number) => {
+    const els = [...(listRef.current?.querySelectorAll<HTMLElement>("[data-tab-index]") ?? [])];
+    return els.findIndex((el) => {
+      const b = el.getBoundingClientRect();
+      return x >= b.left && x <= b.right;
+    });
+  };
+  const springAt = (e: DragEvent) => {
+    const slot = paneDragSlot();
+    const i = hoveredIndexAt(e.clientX);
+    const tab = tabs[i];
+    // Only a pane drag, onto a tab not on screen that does not hold it.
+    const target =
+      slot !== null &&
+      tab &&
+      !settings?.active &&
+      tab.index !== groups.active &&
+      !tab.slots.includes(slot)
+        ? i
+        : null;
+    if ((spring.current?.at ?? null) === target) return;
+    stopSpring();
+    if (target === null || !tab) return;
+    const index = tab.index;
+    spring.current = {
+      at: target,
+      timer: setTimeout(() => {
+        spring.current = null;
+        if (paneDragSlot() === null) return;
+        onGroupsChange((g) =>
+          g.active === index || !g.groups[index] ? g : { ...g, active: index }
+        );
+      }, SPRING_MS),
+    };
+  };
+  // An overflowing bar has no scrollbar: near either end, a drag scrolls it.
+  const edgeScroll = (x: number) => {
+    const list = listRef.current;
+    if (!list || list.scrollWidth <= list.clientWidth) return;
+    const b = list.getBoundingClientRect();
+    if (x < b.left + EDGE_SCROLL_PX) list.scrollLeft -= 16;
+    else if (x > b.right - EDGE_SCROLL_PX) list.scrollLeft += 16;
+  };
   const endDrag = () => {
     dragged.current = [];
+    stopSpring();
     setDropAt(null);
     setJoinAt(null);
   };
@@ -250,6 +335,8 @@ export function ConsoleTabs({
       if (!isBarDrag(e)) return;
       e.preventDefault();
       e.dataTransfer.dropEffect = "move";
+      edgeScroll(e.clientX);
+      springAt(e);
       const join = joinIndexAt(e.clientX);
       const at = join === null ? dropIndexAt(e.clientX) : null;
       setJoinAt((d) => (d === join ? d : join));
@@ -257,6 +344,7 @@ export function ConsoleTabs({
     },
     onDragLeave: (e: DragEvent) => {
       if (e.currentTarget.contains(e.relatedTarget as Node | null)) return;
+      stopSpring();
       setDropAt(null);
       setJoinAt(null);
     },
@@ -325,7 +413,10 @@ export function ConsoleTabs({
   const sessionOf = (r: RunHandle) => (r.sessionId ? sessions?.get(r.sessionId) : undefined);
   const toolLabel = (r: RunHandle) =>
     r.tool === "shell" ? t("tabs.terminal") : aiTools.label(r.tool);
-  const label = (r: RunHandle) => runName(r, sessionOf(r), toolLabel(r), t("tabs.terminal"));
+  const label = (r: RunHandle) => {
+    const name = runName(r, sessionOf(r), toolLabel(r), t("tabs.terminal"));
+    return workspaceOf ? `${workspaceOf(r)} · ${name}` : name;
+  };
   const tabLabel = (tab: Tab) => tab.runs.map(label).join(" | ");
   // A combo's dot is its most urgent AI pane's; a shell has none.
   const tabState = (tab: Tab): RunState | null => {
@@ -344,30 +435,10 @@ export function ConsoleTabs({
     }
   };
 
-  // An AI session may be mid-turn: stopping a tab holding one asks first. A
-  // shell holds no agent.
-  const close = async (tab: Tab) => {
-    if (
-      tab.runs.some((r) => r.tool !== "shell") &&
-      !(await confirmDialog({
-        title:
-          tab.runs.length > 1
-            ? t("tabs.stopGroupTitle", { count: tab.runs.length })
-            : t("tabs.stopTitle", { name: label(tab.focus) }),
-        message: t("tabs.stopBody"),
-        confirmLabel: t("tabs.stopConfirm"),
-        destructive: true,
-      }))
-    )
-      return;
-    for (const r of tab.runs) {
-      try {
-        await api.run.kill(r.id);
-        onClosed(r.id);
-      } catch (err) {
-        toast.error(err);
-      }
-    }
+  // Stop archives the tab's sessions; Sleep keeps them listed to resume
+  // (`endRuns` asks first for an AI pane, which may be mid-turn).
+  const close = async (tab: Tab, sleep = false) => {
+    for (const id of await endRuns(tab.runs, { sleep, name: label(tab.focus), t })) onClosed(id);
   };
 
   const startRename = (r: RunHandle) => {
@@ -388,8 +459,9 @@ export function ConsoleTabs({
   };
 
   // APG tabs: one tab stop; arrows, Home and End move between the tabs.
+  const keys = [...tabs.map((x) => x.key), ...(settings ? [SETTINGS_KEY] : [])];
   const onTabKey = (e: ReactKeyboardEvent, i: number) => {
-    const last = tabs.length - 1;
+    const last = keys.length - 1;
     const to =
       e.key === "ArrowRight"
         ? i === last
@@ -404,11 +476,14 @@ export function ConsoleTabs({
             : e.key === "End"
               ? last
               : null;
-    if (to === null || !tabs[to]) return;
+    const key = to === null ? undefined : keys[to];
+    if (key === undefined) return;
     e.preventDefault();
-    tabRefs.current.get(tabs[to].key)?.focus();
+    tabRefs.current.get(key)?.focus();
   };
-  const tabStop = tabs.find((x) => x.index === groups.active)?.key ?? tabs[0]?.key;
+  const tabStop = settings?.active
+    ? SETTINGS_KEY
+    : (tabs.find((x) => x.index === groups.active)?.key ?? keys[0]);
 
   // A tab-menu item: close the menu, then act on the tab it was opened on.
   const pickTab = (fn: (tab: Tab) => unknown) => () => {
@@ -447,7 +522,7 @@ export function ConsoleTabs({
         className="flex min-w-0 items-stretch overflow-x-auto no-scrollbar"
       >
         {tabs.map((tab, i) => {
-          const active = tab.index === groups.active;
+          const active = !settings?.active && tab.index === groups.active;
           const single = tab.runs.length === 1 ? tab.focus : null;
           const state = tabState(tab);
           if (single && renaming === single.id) {
@@ -481,10 +556,11 @@ export function ConsoleTabs({
               draggable
               onDragStart={(e) => {
                 dragged.current = tab.slots;
-                if (single) startPaneDrag(e, single.slot ?? 0);
+                if (single) startPaneDrag(e, single.slot ?? 0, label(single));
                 else {
                   e.dataTransfer?.setData(TAB_DRAG_TYPE, String(tab.index));
                   if (e.dataTransfer) e.dataTransfer.effectAllowed = "move";
+                  setDragChip(e, tabLabel(tab));
                 }
               }}
               onContextMenu={(e) => tabCtx.open(e, tab)}
@@ -545,6 +621,20 @@ export function ConsoleTabs({
                 <span className="truncate">{tabLabel(tab)}</span>
                 {state && <RunDot state={state} />}
               </button>
+              {tab.runs.some(canSleep) && (
+                <button
+                  type="button"
+                  data-testid={`console-tab-sleep-${tab.key}`}
+                  onClick={() => void close(tab, true)}
+                  aria-label={t("tabs.sleep")}
+                  title={t("tabs.sleep")}
+                  className={`shrink-0 rounded p-0.5 hover:bg-surface-4 hover:text-fg-primary ${
+                    active ? "" : "opacity-0 group-hover:opacity-100 focus:opacity-100"
+                  }`}
+                >
+                  <Moon className="h-3.5 w-3.5" />
+                </button>
+              )}
               <button
                 type="button"
                 data-testid={`console-tab-close-${tab.key}`}
@@ -560,6 +650,48 @@ export function ConsoleTabs({
             </div>
           );
         })}
+        {settings && (
+          <div
+            className={`group relative flex shrink-0 items-center rounded-t-md ${
+              settings.active
+                ? "bg-surface-0 text-fg-primary"
+                : "text-fg-muted hover:bg-surface-4 hover:text-fg-secondary"
+            }`}
+          >
+            {settings.active && (
+              <span className="absolute inset-x-2 -bottom-px h-0.5 rounded-full bg-accent" />
+            )}
+            <button
+              type="button"
+              role="tab"
+              aria-selected={settings.active}
+              tabIndex={tabStop === SETTINGS_KEY ? 0 : -1}
+              ref={(el) => {
+                if (el) tabRefs.current.set(SETTINGS_KEY, el);
+                else tabRefs.current.delete(SETTINGS_KEY);
+              }}
+              onKeyDown={(e) => onTabKey(e, keys.length - 1)}
+              data-testid="console-tab-settings"
+              onClick={settings.onOpen}
+              className="flex h-full items-center gap-2 pl-3 pr-1.5 text-sm"
+            >
+              <Settings className="h-4 w-4 shrink-0" />
+              {t("tabs.settings")}
+            </button>
+            <button
+              type="button"
+              data-testid="console-tab-settings-close"
+              onClick={settings.onClose}
+              aria-label={t("tabs.closeSettings")}
+              title={t("tabs.closeSettings")}
+              className={`mr-2 shrink-0 rounded p-0.5 hover:bg-surface-4 hover:text-fg-primary ${
+                settings.active ? "" : "opacity-0 group-hover:opacity-100 focus:opacity-100"
+              }`}
+            >
+              <X className="h-3.5 w-3.5" />
+            </button>
+          </div>
+        )}
       </div>
       <div ref={menuRef} className="relative flex items-center px-1.5">
         <button
@@ -609,7 +741,10 @@ export function ConsoleTabs({
               type="button"
               role="menuitem"
               className={`${item} !text-fg-muted`}
-              onClick={() => navigate("/settings/agents")}
+              onClick={() => {
+                setMenuOpen(false);
+                navigate(settingsHref("agents"));
+              }}
             >
               <Settings2 className="h-4 w-4" />
               {t("tabs.agentSettings")}
@@ -647,6 +782,14 @@ export function ConsoleTabs({
             </>
           )}
           <MenuSeparator />
+          {ctxTab.runs.some(canSleep) && (
+            <MenuItem
+              testId="console-tab-menu-sleep"
+              onSelect={pickTab((tab) => void close(tab, true))}
+            >
+              {t("tabs.sleep")}
+            </MenuItem>
+          )}
           <MenuItem danger onSelect={pickTab((tab) => void close(tab))}>
             {t("tabs.close")}
           </MenuItem>