@liguoshuai/pi-web-chat 1.5.0 → 1.7.0

package/README.md

@@ -8,17 +8,18 @@
 
 ---
 
-## 📸 功能
-
-- 💬 **流式对话** —— 文本逐字流式渲染，带打字光标
-- 🗂️ **会话历史** —— 自动读取 `~/.pi/agent/sessions/` 下所有历史会话，按首条用户消息做标题
-- 🆕 **新建 / 切换会话** —— 通过左侧栏点击或生成中新建
-- ⚙️ **工具调用折叠块** —— bash / read / write / edit 等以可折叠卡片显示，实时输出
-- 💭 **思考过程折叠块** —— 模型 thinking 以独立可折叠卡片显示
-- 🧩 **模型切换** —— 顶栏模型 pill，覆盖所有 pi 已配置的模型
-- ⏹️ **中止生成** —— 生成中点击发送按钮即可中断
-- ⌨️ **Markdown 渲染** —— 代码块、表格、列表、链接、引用、标题
-- 🖥️ **工作目录绑定** —— 每个 ws 连接由 cwd 决定会话范围（默认 `~`）
+## 📸 功能特性
+
+- 💬 **流式对话** —— 文本逐字流式渲染，带打字光标与 Markdown 高亮
+- ⚡ **后台任务持久化** —— 关闭网页/标签页不中断正在生成的任务，重新进入自动回放（Backfill）追平进度
+- 🌐 **多端/多设备同步协同** —— 多个浏览器标签页或多设备（手机/电脑）可同时连入同一会话，实时双向同步
+- 🧭 **运行时实时插入指令 (Steer)** —— 生成过程中可随时插入转向指令指导 AI 调整后续行动
+- 🗂️ **会话历史与管理** —— 自动读取并显示 `~/.pi/agent/sessions/` 下所有历史会话，实时自动落盘
+- ⚙️ **工具与思考过程折叠** —— bash / read / write / edit 等工具调用与 thinking 思考卡片实时展开/收起
+- 🧩 **动态模型切换** —— 顶栏模型胶囊，零延迟覆盖所有 pi 已配置的模型
+- 🔄 **断线自动重连与心跳** —— 带指数退避自动重连、双向心跳 Ping/Pong 检测
+- 📋 **快捷复制** —— 支持代码块、工具指令、回答全文一键复制
+- 📱 **移动端响应式** —— Viewport `100dvh` 优化、顶栏常驻固定、滚动置顶/置底快捷悬浮按钮（FAB）
 
 ---
 
@@ -28,19 +29,26 @@
 cd pi-web-chat
 npm install
 
-# 确保 pi 已安装并已配置好至少一个 provider/model：
+# 确保 pi 已安装并已配置好至少一个 provider：
 #   pi         （交互模式 → 运行 /login 选择 provider，或设置 API key）
 npm start
 # → http://localhost:3000
 ```
 
-### 环境变量
+---
+
+## ⚙️ 环境变量配置
 
-| 变量                  | 默认值                                     | 说明                          |
-| -------------------- | --------------------------------------- | --------------------------- |
-| `PORT`               | `3000`                                  | Web 服务监听端口                    |
-| `PI_BIN`             | 自动探测（`~/.npm-global/bin/pi` 等）             | 显式指定 pi 可执行文件路径                |
-| `PI_SESSIONS_DIR`    | `~/.pi/agent/sessions`                  | pi 的 session 存储目录           |
+| 变量 | 默认值 | 说明 |
+| ---- | ------ | ---- |
+| `PORT` | `3000` | Web 服务监听端口 |
+| `PI_BIN` | 自动探测（`~/.npm-global/bin/pi` 等） | 显式指定 pi 可执行文件绝对路径 |
+| `PI_SESSIONS_DIR` | `~/.pi/agent/sessions` | pi 的 session 存储目录 |
+| `IDLE_TIMEOUT_MS` | `300000` (5分钟) | 真正空闲（无连接+非流式）后的进程回收超时（0 为禁用回收） |
+| `MAX_AGENT_LIFETIME_MS` | `1800000` (30分钟) | 单个 Agent 进程后台生存硬上限（0 为无上限） |
+| `EVENT_BUFFER_SIZE` | `2000` | 离线环形 Buffer 允许缓存的最大事件条数 |
+| `MAX_CONCURRENT_AGENTS` | `0` (无限制) | 进程池最大并发 Agent 进程数量 |
+| `IDLE_DROP_HEAP` | `false` | 进入空闲时是否给 V8 引擎 GC 提示（需 `--expose-gc`） |
 
 ---
 
@@ -49,31 +57,38 @@ npm start
 ```
 pi-web-chat/
 ├── README.md                       本文件
-├── DESIGN.md                       设计文档（架构、数据流、决策）
-├── ISSUES.md                       历次问题排查与修复
-├── CHANGELOG.md                    版本变更日志
 ├── package.json
 ├── package-lock.json
-├── server.js                       Express + WebSocket，桥接 pi RPC
-├── .gitignore
-└── public/
-    ├── index.html                  单页 UI
-    ├── app.js                      前端逻辑
-    └── style.css                   ChatGPT/Gemini 风格样式
+├── server.js                       Express + WebSocket，桥接 pi RPC 与进程池管理
+├── bin/
+│   └── pi-web-chat.js              CLI 可执行入口
+├── public/
+│   ├── index.html                  单页 UI
+│   ├── app.js                      前端逻辑与状态机
+│   └── style.css                   ChatGPT/Gemini 风格样式
+└── docs/                           项目文档库
+    ├── ARCHITECTURE.md             架构设计文档
+    ├── DESIGN.md                   详细设计与决策文档
+    ├── ISSUES.md                   历次问题排查与修补记录
+    └── CHANGELOG.md                版本变更日志
 ```
 
 ---
 
-## 🏗️ 架构
+## 🏗️ 架构概览
 
 ```
- 浏览器 ──WebSocket(/ws?cwd=...&session=...)──► Node server.js ──stdin/stdout(JSONL)──► pi --mode rpc
-                                             (一个 ws 连接 spawn 一个 pi 子进程)
-                                             │
-                                             ├──REST /api/sessions ──► 直读 JSONL 列历史
-                                             └──REST /api/session?file=... ─► 重建根→叶路径
+ 浏览器 (多 Tab / 多设备) ──WebSocket(/ws?cwd=...&session=...)──► Node server.js
+                                                                (Session Key 进程池 activeAgents)
+                                                                │
+                                                                ├──► pi --mode rpc (后台持久化 Worker)
+                                                                ├──► REST /api/sessions ──► 列会话历史
+                                                                ├──► REST /api/session ────► 构建对话链
+                                                                └──► REST /api/agents ─────► 实时监控看板
 ```
 
+详细架构说明与设计决策请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 与 [docs/DESIGN.md](docs/DESIGN.md)。
+
 ---
 
 ## 📝 License
@@ -94,11 +109,6 @@ MIT
 ./scripts/install-service.sh 8080
 ```
 
-脚本会：
-1. 在 `~/.config/systemd/user/pi-web-chat.service` 生成 unit
-2. `systemctl --user daemon-reload && systemctl --user enable --now pi-web-chat`
-3. 设置 `Restart=on-failure` 自动重启
-
 查看状态 / 日志：
 ```bash
 systemctl --user status pi-web-chat
@@ -110,7 +120,7 @@ journalctl --user -u pi-web-chat -f
 > sudo loginctl enable-linger $USER
 > ```
 
-卸载：
+卸载服务：
 ```bash
 systemctl --user disable --now pi-web-chat
 rm ~/.config/systemd/user/pi-web-chat.service

package/docs/ARCHITECTURE.md

@@ -0,0 +1,179 @@
+# 架构设计文档
+
+> pi-web-chat 的技术架构、数据流、关键设计决策与扩展点说明（对应 v1.6.0 版本）。
+
+---
+
+## 1. 高层架构
+
+```
+┌─────────────────┐             WebSocket (JSON)             ┌──────────────────────┐
+│  Browser Tab A  │ ◄──────────────────────────────────────► │                      │
+└─────────────────┘                                          │                      │
+┌─────────────────┐                                          │  Node.js server      │
+│  Browser Tab B  │ ◄──────────────────────────────────────► │  (server.js)         │
+└─────────────────┘                                          │                      │
+                                                             │  ┌────────────────┐  │
+                                                             │  │  PiAgent Pool  │  │
+                                                             │  │ (activeAgents) │  │
+                                                             │  └───────┬────────┘  │
+                                                             └──────────┼───────────┘
+                                                                        │
+                                                    spawn child_process │ (1 agent per session key)
+                                                                        ▼
+                                                             ┌──────────────────────┐
+                                                             │   pi --mode rpc      │
+                                                             │   (后台 Agent 子进程)  │
+                                                             │   stdin/stdout       │
+                                                             └──────────┬───────────┘
+                                                                        │
+                                                     ┌──────────────────┼──────────────────┐
+                                                     ▼                  ▼                  ▼
+                                            ~/.pi/agent/sessions/   ~/.pi/agent/       配置/扩展/
+                                            --home-zrlgs--/         extensions/        skills/
+                                                    │
+                                                    ▼
+                                            *.jsonl (append-only tree)
+```
+
+**核心设计原则**：
+- **按 Session Key 池化进程**：以 `${cwd}:${resolvedSessionPath}` 作为唯一 Key，多标签页或多设备连接同一个 Session 时共享同一个后台 `PiAgent` 进程。
+- **后台持久化运行（Headless Persistence）**：网页断开（如关闭标签页）不会立即终止进程。只要 Agent 处于流式生成或有未响应请求状态，后台进程会坚持跑完当前任务。
+- **离线事件环形缓存与回放（Ring Buffer & Backfill）**：无客户端连接时，pi 输出的事件自动存入环形 Buffer（默认 2000 条）。客户端重连时通过 `backfill_start` → 离线事件 → `backfill_end` 进行增量补齐。
+- **真正空闲回收（True-Idle Timeout）**：仅在“无 WebSocket 连接”且“进程彻底进入 idle（非 streaming、无挂起 RPC）”时，才启动 `IDLE_TIMEOUT_MS` 空闲回收倒计时。
+- **磁盘 JSONL 为唯一真理（Single Source of Truth）**：会话历史与树状分支全由 pi 本身维护在磁盘 `.jsonl` 文件中，Web 端通过 REST 接口与 RPC 消息与文件保持同步。
+
+---
+
+## 2. 关键数据流
+
+### 2.1 打开已有会话与增量回放（Backfill）
+
+```
+Browser                          server.js                      PiAgent (RPC)
+  │                                 │                                │
+  ├─ GET /api/session?file=X ──────►│ 读 JSONL 主干消息               │
+  │◄─── { header, entries[] }──────┤                                │
+  │                                 │                                │
+  ├─ 渲染历史消息                    │                                │
+  │                                 │                                │
+  ├─ WS /ws?cwd=...&session=X ─────►│ 查找/创建 activeAgents[Key]     │
+  │                                 ├─► attachWs(ws)                 │
+  │                                 ├─► 发现有离线缓存事件            │
+  │◄─── { type: "backfill_start" }─┤                                │
+  │◄─── N 条离线事件 (text_delta…)  │ (将离线事件批量回放给当前 ws)      │
+  │◄─── { type: "backfill_end" }───┤                                │
+  │                                 │                                │
+  ├─ 矫正当前 streaming 与 Composer 状态                              │
+```
+
+### 2.2 新建会话与发送消息
+
+```
+Browser                         server.js                       pi RPC 子进程
+  │                                │                                 │
+  ├─ WS /ws?cwd=... (无 session)   │ spawn pi --mode rpc             │
+  │                                │◄─ pi 创建新 session jsonl       │
+  │◄─── ws open (状态记为已连接)     │                                 │
+  │                                │                                 │
+  ├─ sendWs({type:"prompt", ...})─►│────────────────────────────────►│
+  │                                │                                 ├─ agent_start (state=streaming)
+  │◄─── message_update/text_delta ─┼◄────────────────────────────────┤
+  │◄─── agent_settled              │◄────────────────────────────────┤ (state=idle)
+  │                                │                                 ├─ session 文件实时追加
+```
+
+### 2.3 中途插话 / 转向（Mid-turn Steering）
+
+```
+Browser                         server.js                       pi RPC 子进程
+  │                                │                                 │
+  ├─ Agent 处于 streaming 状态 ────┼─────────────────────────────────┤ (正在执行长任务/工具)
+  ├─ sendWs({type:"steer", ...})──►│────────────────────────────────►│
+  │                                │                                 ├─ 注入 steer 命令
+  │◄─── agent 收到并调整后续思考 ────┼◄────────────────────────────────┤
+```
+
+---
+
+## 3. 关键模块职责
+
+### 3.1 `server.js`
+
+| 模块/函数 | 职责 |
+|-----------|------|
+| `PiAgent` 类 | 管理单个 `pi --mode rpc` 子进程：维护状态（`idle`/`streaming`）、离线事件 Buffer、挂起请求表、真·空闲回收定时器与硬生存上限定时器。 |
+| `activeAgents` Map | 以 `${cwd}:${sessionFile}` 为 Key 的进程池，实现多端/多标签页共享。 |
+| `GET /api/sessions` | 扫描 `~/.pi/agent/sessions/**/*.jsonl`，读取 header 做 cwd 过滤，按更新时间排序返回。 |
+| `GET /api/session` | 读取单个 `.jsonl` 文件，按 parentId 关系重构叶子到根节点的标准对话链。 |
+| `GET /api/agents` | 暴露后台活跃 Agent 的状态信息（运行状态、客户端数量、存活时长、离线 Buffer 消息数、最近提示词等）。 |
+| `WebSocketServer` | 处理连接建立与断开，分发 `prompt`、`steer`、`abort`、`ping` 等指令，并在 `SIGINT`/`SIGTERM` 时进行优雅关闭。 |
+
+### 3.2 `public/app.js`
+
+| 模块/函数 | 职责 |
+|-----------|------|
+| `state` | 全局状态对象：维护 `wsConnected`、`streaming`、`isBackfilling`、`activeToolCalls`、`sessionId`、`wsGen` 等。 |
+| `connectWs(opts)` | 管理 WebSocket 生命周期：携带代次 `wsGen` 防止旧消息污染，处理重连逻辑与心跳。 |
+| `handlePiMessage(obj)` | 核心事件分发器：处理 `backfill_start`/`backfill_end`、16 种 pi 事件以及状态同步。 |
+| `ensureStreamingMsg / refreshStreamingContent` | 增量渲染/更新正在流式的文本、思考过程（Thinking）与工具卡片。 |
+| `renderMarkdown` | 自研轻量 Markdown 渲染器（代码块抠出保护、Html Escape、行内语法转换）。 |
+
+### 3.3 `public/style.css`
+
+- 暗色与明色响应式样式变量。
+- 左侧 260px 侧边栏与右侧主聊天区自适应布局。
+- 移动端 Fixed 顶栏、Viewport height 100dvh 适配与悬浮置顶按钮（FAB）。
+
+---
+
+## 4. 关键设计决策
+
+| 决策点 | 选择 | 理由 |
+|--------|------|------|
+| **进程池粒度** | **Session Key 池化** | 允许同一会话在多设备/多 Tab 间同步，同时保证进程资源不重复浪费。 |
+| **断连处理** | **后台继续跑 + 环形 Buffer 回放** | 解决关闭标签页导致未完成任务断掉的问题；用环形 Buffer 防止长时间离线膨胀内存。 |
+| **回收策略** | **真·空闲倒计时（True-Idle Timeout）** | 区分“无连接”与“真正的空闲”，保障长时间后台生成任务不被中断。 |
+| **通讯协议** | **直接透传 pi 原生 JSONL** | 不做二次包装，保持与 pi RPC 协议同频更新。 |
+| **持久化** | **复用 pi 本身 .jsonl** | 零额外存储依赖，Web 端与终端命令完全同源共享会话。 |
+
+---
+
+## 5. 配置与环境变量
+
+| 环境变量 | 默认值 | 说明 |
+|----------|--------|------|
+| `PORT` | `3000` | HTTP 与 WebSocket 监听端口 |
+| `PI_BIN` | 自动探测 | pi 可执行文件绝对路径 |
+| `PI_SESSIONS_DIR` | `~/.pi/agent/sessions` | 会话 JSONL 文件存取目录 |
+| `IDLE_TIMEOUT_MS` | `300000` (5分钟) | 真正空闲（无连接+非流式）后的回收超时（0 为禁用回收） |
+| `MAX_AGENT_LIFETIME_MS` | `1800000` (30分钟) | 单个 Agent 进程后台生存硬上限（0 为无上限） |
+| `EVENT_BUFFER_SIZE` | `2000` | 离线环形 Buffer 允许缓存的最大事件条数 |
+| `MAX_CONCURRENT_AGENTS` | `0` (无限制) | 进程池最大并发 Agent 进程数量 |
+| `IDLE_DROP_HEAP` | `false` | 进入空闲时是否给 V8 引擎 GC 提示（需 `--expose-gc`） |
+
+---
+
+## 6. 目录结构
+
+```
+pi-web-chat/
+├── README.md                       # 主说明文档
+├── package.json
+├── package-lock.json
+├── server.js                       # Express + WebSocket 服务器与 PiAgent 管理
+├── bin/
+│   └── pi-web-chat.js              # 可执行入口
+├── public/
+│   ├── index.html                  # 单页 UI
+│   ├── app.js                      # 前端逻辑与状态机
+│   └── style.css                   # CSS 样式
+├── docs/                           # 所有文档统一收纳
+│   ├── ARCHITECTURE.md             # 架构设计文档（本文件）
+│   ├── DESIGN.md                   # 详细设计与决策文档
+│   ├── ISSUES.md                   # 排查与修补记录
+│   └── CHANGELOG.md                # 版本变更日志
+└── scripts/                        # 服务安装/卸载脚本
+    ├── install-service.sh
+    └── pi-web-chat.service
+```

package/{CHANGELOG.md → docs/CHANGELOG.md}

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.7.0] - 2026-07-26
+
+### Added
+- **前端流式渲染防抖节流 (rAF UI Throttling)**：使用 `requestAnimationFrame` 节流高频 Token/Delta 事件，消除倒水式输出时的 DOM 频繁销毁与全量重塑，大幅提升高频打字时的流畅帧率，显著降低 CPU 和发热消耗。
+- **后端 Session 列表 mtime 内存缓存 (Session Metadata Caching)**：`/api/sessions` 引入基于文件修改时间（`mtimeMs`）的元数据内存缓存。对无改动的历史 Session 文件跳过磁盘读取与全量 JSON 逐行解析，大幅提升侧边栏列表加载响应速度。
+- **离线事件 Buffer 算法优化 (Ring Buffer O(1) Push)**：将 `PiAgent.bufferEvent` 从 $O(N)$ 复杂度的 `Array.shift()` 改为 $O(1)$ 的指针环形队列，消除无客户端连接时的数组平移消耗。
+- **WebSocket 垃圾连接自动回收 (Dead Socket Cleanup)**：在 `wsSend` 广播消息时动态检测并自动剔除已处于关闭状态（`CLOSING`/`CLOSED`）的垃圾 Socket 引用，避免泄露。
+
+---
+
+## [1.6.0] - 2026-07-26
+
+### Added
+- **后台任务继续运行 (Background Task Persistence)**：
+  - 关闭浏览器/标签页不再强制中止正在生成的 pi 任务：后台 pi RPC 子进程保持**跑完当前这一轮**；重连后可看到完整结果。
+  - `PiAgent` 跟踪 `state`（`idle`/`streaming`）与 `pending` 请求。只有在“**无 WebSocket 且真正空闲**”（无 streaming 也无未响应请求）时才启动空闲回收计时。
+  - 时长型缓冲区：在后台期间渲染器产出的事件会被**离线缓存**到 `EVENT_BUFFER_SIZE`（默认 2000 条）的环形 buffer。新连接上来时自动 **回放**为 `backfill_start` → N 条原始事件 → `backfill_end` 三个阶段包裹的消息，便于前端精确“追到哪儿”。
+  - 新增 REST 端点 `GET /api/agents`：查看所有存活后台 pi 代理（`state`, `alive`, `busy`, `hasClients`, `uptimeMs`, `bufferedEvents`, 最近一条用户提示等）。常驻 npm 下载、上传、调试或后台 面板都可以利用。
+  - 新增环境变量：`MAX_AGENT_LIFETIME_MS`（默认 1800000 = 30分钟，硬上限超出强制 `SIGTERM`；设为 0 禁用）。防止后台代理失控常驻。
+
+### Changed
+- **`IDLE_TIMEOUT_MS` 语义重要变更**：从“**断开后多久**杀进程”变为“**真正空闲后多久**才回收”（默认还是 5min）。如果断开后还在 streaming 或有余未完成的 RPC 请求，定时器不会触发，任务不会被中断。
+- 首页顶栏重连后会同步服务器状态：收到 `backfill_end` 后会自动滚动到底，并恢复 `streaming` 状态（如仍在后台继续）。
+- 首页增加优雅关闭：`SIGINT`/`SIGTERM` 会“逐个停止所有后台 pi 进程”后再退出，防止 server 重启时留下 zombie 进程。
+- 不再支持“`IDLE_TIMEOUT_MS=0` 断开即杀”告诉——该环境变量现在表示“**禁用空闲回收**”。需要立刻释放内存，请改为正数（如 `5000`）或重启 server。
+
+### 技术说明
+- `PiAgent` 生命周期事件：`agent_start → state=streaming`；`agent_end/agent_settled → state=idle`；`pi_exit → state=idle`。这是“背景继续跑完”的关键开关。
+
+---
+
 ## [1.5.0] - 2026-07-26
 
 ### Added
@@ -132,14 +163,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 多模型切换（pi 配置的所有 provider/model）
 - 响应式深色主题（ChatGPT/Gemini 风格）
 
-### Technical Debt (已知)
-- 图片上传未接
-- 多 cwd / 项目切换器未做
-- fork / tree / clone 浏览未接
-- 浅/深主题切换未做
-- 双端实时同步未做
-- 鉴权未做
-
 ---
 
 ## Legend

package/docs/DESIGN.md

@@ -0,0 +1,88 @@
+# 详细设计与决策文档
+
+## 目标
+
+将 [pi](https://pi.dev) 终端编码代理包装为一个**类 ChatGPT / Gemini 的 Web 界面**，使用户能够：
+
+- 在浏览器中与 pi 展开对话，享受流式文本输出、思考过程卡片、Markdown 渲染与工具调用可视化；
+- 与终端共享会话历史（一份存储、两端可见）；
+- 支持后台持久化运行：关闭标签页或切换设备不打断正在生成的任务，重新进入时自动追进度。
+
+非目标：
+- 引入复杂的前端构建链（保持单页原生 JS/CSS，无打包工具）；
+- 替代 pi 本身的文件存储层或重新实现数据库。
+
+---
+
+## 核心设计与进程模型
+
+### 进程池化与后台持久化运行
+
+```
+Browser Tab 1 ──┐
+                ├── WebSocket ──► server.js (activeAgents[Key]) ──stdio (JSONL)──► pi (rpc mode)
+Browser Tab 2 ──┘
+```
+
+与早期“1 个 WebSocket = 1 个子进程”不同，当前设计以 **Session Key**（`${cwd}:${resolvedSessionPath}`）作为唯一标识：
+
+1. **多端/多标签页共享**：多个浏览器标签页或多个设备打开同一个 Session 时，附加到同一个 `PiAgent` 实例。
+2. **后台任务持久化**：关闭网页仅表示断开 WebSocket 连接，`PiAgent` 会继续运行直到当前的流式任务结束。
+3. **离线 Buffer 与回放**：在无客户端连接期间，pi 抛出的事件将缓存在 `eventBuffer` 环形队列中。新客户端连接后，服务端通过 `backfill_start` → 增量事件 → `backfill_end` 进行追回。
+4. **真·空闲回收（True-Idle Timeout）**：仅在“无 WebSocket 连接”且“真正 Idle”（非 streaming，无挂起 RPC 请求）时启动 `IDLE_TIMEOUT_MS`（默认 5 分钟）倒计时回收进程。
+
+---
+
+## 数据流设计
+
+### 1. 消息发送与流式渲染
+
+```
+1. 浏览器发送 JSON: {"type": "prompt", "message": "..."}
+2. 服务端转给对应 Session 的 PiAgent
+3. PiAgent 更新状态为 streaming，写入 pi 的 stdin
+4. pi 往 stdout 输出事件流 (agent_start / text_delta / toolcall_start / agent_end / agent_settled)
+5. 服务端广播给所有连入该 Session 的 WebSocket，并写入离线 Buffer（若无连接）
+6. 浏览器 handlePiMessage 增量更新 DOM（文本、思考块、工具卡片）
+```
+
+### 2. 中途中断与转向（Steering）
+
+在代理正在执行长任务或工具调用时，用户可以输入补充指令：
+- **Abort**：发送 `{"type": "abort"}` 中断当前生成。
+- **Steer**：发送 `{"type": "steer", "message": "..."}` 插入中途指令，指导代理调整后续行动。
+
+---
+
+## 关键设计决策与权衡
+
+### 1. 渲染策略：重构 vs 增量 DOM
+
+针对流式输出中出现的文本、思考块（Thinking）、工具卡片交错问题：
+- 选择**每次更新时重构当前 assistant 消息的内容节点**。因为单次回复文本长度通常有限，原生 DOM 节点重写开销在 5ms 以内，极大地简化了复杂的节点插入与折叠逻辑。
+
+### 2. 代次标记（`wsGen`）
+
+解决浏览器在极短时间内快速切换 WebSocket 会话时的竞态：
+- 全局分配单调递增的 `wsGen` 代次。每次建立新 WebSocket 时递增。在接收消息前比对 `ws._gen === wsGen`，避免旧连接迟到的消息破坏新会话的状态。
+
+### 3. Markdown 渲染：Escape-First 零依赖
+
+不使用第三方大型 Markdown 渲染库，采用原生轻量处理：
+- 在渲染入口统一对文本做 HTML Escape 转义（防止 XSS 攻击）；
+- 先将围栏代码块（Fenced Code Blocks）抠出暂存，再做行内语法转换，最后还原代码块。
+
+---
+
+## 消息事件与 UI 控件对照表
+
+| pi RPC 事件 | 触发动作 / 前端 UI 表现 |
+|-------------|-------------------------|
+| `agent_start` | 切换发送按钮为“停止/中止”状态，标志进入流式生成状态 |
+| `message_start` | 在聊天区域末尾追加新的 Assistant 消息卡片 |
+| `message_update` / `text_delta` | 累加到文本缓冲并重新渲染 Markdown |
+| `message_update` / `thinking_delta` | 累加到 Thinking 折叠卡片并实时显示 |
+| `message_update` / `toolcall_start` | 创建可视化工具调用卡片（可折叠） |
+| `tool_execution_start / update / end` | 动态更新工具卡片的输入参数、标准输出与执行状态 |
+| `agent_end` / `agent_settled` | 恢复发送按钮，标记流式生成结束，触发侧边栏会话列表刷新 |
+| `backfill_start` / `backfill_end` | 前端标记处于历史回放状态，回放期间暂停自动滚动，回放结束后一次性同步状态并滚动到底部 |

package/docs/ISSUES.md

@@ -0,0 +1,66 @@
+# 问题排查与修补记录
+
+项目开发与演进过程中遇到并修复的技术问题与设计优化记录。
+
+---
+
+## 1. 侧边栏 `cwd` 路径编码错误
+
+**症状**：API `GET /api/sessions?cwd=/home/zrlgs` 拿不到任何结果。
+
+**根因**：第一版用了 `cwd.replace(/\//g, "-")` 把 `/home/zrlgs` 编码成 `-home-zrlgs`，但 pi 实际上用的是 `--home-zrlgs--`（前后都带 `-`）。
+
+**修复**：弃用编码猜测，扫描 sessions 根目录下所有子目录，读每个 jsonl 的 header 里 `cwd` 字段，再按 `cwd` 严格比对过滤。
+
+---
+
+## 2. 关闭网页标签页导致正在生成的 pi 任务中断
+
+**症状**：在用户提交了一个复杂 Prompt（或正在跑 Bash 工具）后关闭网页，AI 回答直接中断，下次连入时拿不到完整结果。
+
+**根因**：原先 WebSocket 断开会直接触发 5 分钟倒计时杀进程；即使倒计时未到，没有客户端连入时生成的事件也被直接抛弃，未在内存中保留。
+
+**修复**：
+- 引入 **PiAgent 进程池化** 与 **真·空闲回收（True-Idle Timeout）**：只有在“无 WS 连接”且“真正 Idle”（非 streaming、无挂起 RPC）时才倒计时。
+- 引入 **离线事件环形 Buffer（Event Ring Buffer）**：无客户端时缓存在 Buffer，新连接重连时发送 `backfill_start` → 增量事件 → `backfill_end` 进行追回并一次性同步状态。
+
+---
+
+## 3. 局域网 / 移动端 Safari 100vh 动态导航栏遮挡底部输入框
+
+**症状**：移动端 Safari 浏览器打开 Web 界面时，底部输入框被 iOS 动态地址栏遮挡，且顶栏在滚动时会跟着滑走。
+
+**修复**：
+- 在 CSS 中使用 `100dvh` (Dynamic Viewport Height) 替代 `100vh`。
+- 将顶栏改为 `sticky` / `fixed` 布局，保障移动端交互体验。
+- 增加悬浮置顶/置底快捷按钮（FAB）。
+
+---
+
+## 4. WebSocket 代次竞态 —— 旧 socket 残留消息污染新会话
+
+**症状**：点“新对话”快速发消息时，前一次会话延迟到达的 `agent_end` / `agent_settled` 事件跑进新会话，导致新会话 `streaming` 状态被错误覆盖。
+
+**修复**：
+- 引入全局 `wsGen` 单调递增计数器，给每个 WebSocket 分配 `_gen` 编号。
+- 接收消息前比对代次，丢弃非当前代次发来的旧事件。
+
+---
+
+## 5. `/api/session` 中局部变量遮蔽 Node `path` 模块
+
+**症状**：在调用 `/api/session` 接口获取历史对话时，出现 `TypeError: path.basename is not a function` 报错。
+
+**根因**：函数内部在处理 jsonl 包含的文件条目时，使用了 `const path = ...` 局部变量名，屏蔽了 Node.js 顶层的 `import path from "node:path"` 模块。
+
+**修复**：重命名局部变量为 `filePath` / `resolvedPath`，消除变量同名遮蔽。
+
+---
+
+## 6. 多设备 / 多 Tab 共享会话不同步
+
+**症状**：同一个 Session 在手机和电脑上同时打开时，手机发送的消息电脑看不到，状态互相覆盖。
+
+**修复**：
+- 以 Session Key 为粒度管理 `PiAgent` 实例。
+- 任何一个客户端发送 `prompt` 或 `steer` 指令时，通过 `agent.wsSend(..., senderWs)` 广播同步给连入该 Session 的其他客户端。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liguoshuai/pi-web-chat",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "A ChatGPT/Gemini-style web UI for the pi coding agent, powered by pi's RPC mode.",
   "type": "module",
   "main": "server.js",
@@ -11,8 +11,8 @@
     "server.js",
     "bin/",
     "public/",
+    "docs/",
     "README.md",
-    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/public/app.js

@@ -40,6 +40,7 @@ const state = {
   currentModel: null,
   thinkingLevel: "medium",
   sessionId: null,
+  isBackfilling: false,
 };
 
 let toastTimer = null;
@@ -431,6 +432,26 @@ function closeSidebar() {
   $(".app").classList.remove("sidebar-open");
 }
 
+function initMobileToolbarFab() {
+  const chat = $("#chat");
+  const fab = $("#mobileToolbarFab");
+  if (!chat || !fab) return;
+
+  const onScroll = () => {
+    if (chat.scrollTop > 250) {
+      fab.classList.add("visible");
+    } else {
+      fab.classList.remove("visible");
+    }
+  };
+
+  chat.addEventListener("scroll", onScroll);
+  fab.addEventListener("click", () => {
+    chat.scrollTo({ top: 0, behavior: "smooth" });
+    fab.classList.remove("visible");
+  });
+}
+
 async function loadSession(file) {
   state.currentSessionFile = file;
   try {
@@ -708,6 +729,8 @@ function summaryArgs(name, args) {
 }
 
 function scrollBottom() {
+  // Don't fight the user during a background-event replay (backfill).
+  if (state.isBackfilling) return;
   const chat = $("#chat");
   chat.scrollTop = chat.scrollHeight;
 }
@@ -750,6 +773,16 @@ function ensureStreamingMsg() {
   return node;
 }
 
+let isRefreshScheduled = false;
+function refreshStreamingContentDebounced() {
+  if (isRefreshScheduled) return;
+  isRefreshScheduled = true;
+  requestAnimationFrame(() => {
+    isRefreshScheduled = false;
+    refreshStreamingContent();
+  });
+}
+
 function refreshStreamingContent() {
   const node = state.streamingMsg;
   if (!node) return;
@@ -996,6 +1029,25 @@ function sendWs(obj) {
 }
 
 function handlePiMessage(obj) {
+  // Backfill markers emitted by the server when it replays buffered events
+  // that happened in the background while no browser was attached.
+  if (obj.type === "backfill_start") {
+    state.isBackfilling = true;
+    return;
+  }
+  if (obj.type === "backfill_end") {
+    state.isBackfilling = false;
+    // After replay, sync the composer / streaming state to what the server thinks.
+    if (obj.streaming) {
+      state.streaming = true;
+      setComposerAborting(true);
+      ensureStreamingMsg();
+      refreshStreamingContent();
+    }
+    // jump to the latest content once the replay is done
+    requestAnimationFrame(scrollBottom);
+    return;
+  }
   // Responses to commands we issued (get_state etc.) come back with success+data.
   if (obj.type === "response") {
     if (obj.command === "get_state" && obj.success) updateState(obj.data);
@@ -1100,7 +1152,7 @@ function handlePiMessage(obj) {
       if (!ev) break;
       if (ev.type === "text_delta") {
         state.streamingText += ev.delta;
-        refreshStreamingContent();
+        refreshStreamingContentDebounced();
       } else if (ev.type === "text_end") {
         // Authoritative final text for this content slot. Overwrite any
         // accumulated/delta text so we display exactly what the model
@@ -1114,7 +1166,7 @@ function handlePiMessage(obj) {
         if (ev.type === "thinking_delta") {
           state.streamingThinking += ev.delta || "";
         }
-        refreshStreamingContent();
+        refreshStreamingContentDebounced();
       } else if (ev.type === "toolcall_start") {
         ensureStreamingMsg();
         const call = ev.toolCall || { id: obj.toolCallId || ev.id, name: obj.toolName, arguments: obj.args };
@@ -1180,7 +1232,7 @@ function handlePiMessage(obj) {
 function ensureToolBlock(toolCallId, name, args) {
   if (state.activeToolCalls.has(toolCallId)) return state.activeToolCalls.get(toolCallId);
   makeToolBlockFromCall({ id: toolCallId, name, arguments: args });
-  refreshStreamingContent();
+  refreshStreamingContentDebounced();
   return state.activeToolCalls.get(toolCallId);
 }
 
@@ -1593,6 +1645,9 @@ function init() {
     }
   });
 
+  // Mobile: floating button to jump back to the toolbar after long scrolls
+  initMobileToolbarFab();
+
   refreshSessions();
   // start in the disconnected state; connectWs will flip to green on open.
   const initDot = $("#connDot");

package/public/index.html

@@ -101,6 +101,14 @@
     </div>
   </div>
 
+  <!-- Mobile toolbar reveal / scroll-to-top FAB -->
+  <button class="mobile-toolbar-fab" id="mobileToolbarFab" title="回到顶部">
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <line x1="12" y1="19" x2="12" y2="5"></line>
+      <polyline points="5 12 12 5 19 12"></polyline>
+    </svg>
+  </button>
+
   <!-- Toast notification -->
   <div class="toast" id="toast"></div>
   <script src="/app.js"></script>

package/public/style.css

@@ -746,6 +746,37 @@ body {
   transform: translateX(-50%) translateY(0);
 }
 
+/* Mobile toolbar reveal / scroll-to-top FAB */
+.mobile-toolbar-fab {
+  position: fixed;
+  right: 16px;
+  bottom: 90px;
+  width: 44px;
+  height: 44px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  background: var(--bg-input);
+  color: var(--text);
+  display: none;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.4);
+  cursor: pointer;
+  z-index: 50;
+  opacity: 0;
+  transform: translateY(10px);
+  pointer-events: none;
+  transition: opacity 0.2s ease, transform 0.2s ease, background 0.15s ease;
+}
+.mobile-toolbar-fab.visible {
+  opacity: 1;
+  transform: translateY(0);
+  pointer-events: auto;
+}
+.mobile-toolbar-fab:active {
+  background: var(--bg-hover);
+}
+
 /* Model selector dropdown */
 .model-menu {
   position: absolute; top: 52px; right: 16px;
@@ -807,33 +838,52 @@ body {
     opacity: 1;
   }
 
-  /* Topbar Mobile Adjustments */
+  /* Topbar Mobile Adjustments — fixed, taller, shadowed so it is always findable */
   .topbar {
-    height: 50px;
-    padding: 0 8px;
-    gap: 6px;
-    flex-shrink: 0;
-    position: sticky;
+    height: 54px;
+    padding: 0 12px;
+    gap: 8px;
+    position: fixed;
     top: 0;
-    z-index: 20;
+    left: 0;
+    right: 0;
+    z-index: 101;
     background: var(--bg);
+    border-bottom: 1px solid var(--border);
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.35);
+  }
+
+  .main {
+    padding-top: 54px;
   }
 
   .topbar .session-name {
-    font-size: 13px;
+    font-size: 14px;
     font-weight: 500;
     min-width: 0;
     flex: 1;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
-    padding: 0 2px;
+    padding: 0 4px;
+  }
+
+  .btn-toggle-sidebar {
+    width: 40px;
+    height: 40px;
+    padding: 0;
+    color: var(--text);
+    background: var(--bg-hover);
+  }
+  .btn-toggle-sidebar svg {
+    width: 22px;
+    height: 22px;
   }
 
   #cwdPillWrap {
-    padding: 4px 8px;
+    padding: 5px 9px;
     font-size: 11px;
-    max-width: 95px;
+    max-width: 90px;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
@@ -841,22 +891,28 @@ body {
   }
 
   .model-pill {
-    padding: 4px 8px;
+    padding: 5px 10px;
     font-size: 11px;
-    max-width: 105px;
+    max-width: 100px;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
     flex-shrink: 0;
   }
 
-  /* Model Dropdown Menu Mobile Adjustments */
+  /* Model Dropdown Menu Mobile Adjustments — fixed so it never detaches from topbar */
   .model-menu {
-    width: calc(100vw - 16px);
-    right: 8px;
+    position: fixed;
+    top: 54px;
     left: 8px;
-    top: 46px;
-    max-height: 280px;
+    right: 8px;
+    width: auto;
+    max-height: calc(100dvh - 70px);
+    border-radius: 12px;
+  }
+
+  .mobile-toolbar-fab {
+    display: flex;
   }
 
   /* Chat area mobile adjustments */

package/server.js

@@ -42,9 +42,13 @@ function normalizeCwd(dir) {
 const SESSIONS_DIR = process.env.PI_SESSIONS_DIR || path.join(home(), ".pi", "agent", "sessions");
 const PORT = process.env.PORT || 3000;
 
-// Idle timeout (ms) before a detached (browser closed) pi RPC subprocess is killed.
-// Replaces the previous hardcoded 5-minute timeout. Lower values free memory faster
-// on memory-constrained hosts; set IDLE_TIMEOUT_MS=0 to disable cleanup entirely.
+// Idle timeout (ms). When a pi agent has NO WebSocket attached AND is truly
+// idle (no streaming/pending tasks), after this many ms the subprocess is
+// killed to reclaim memory. Browser-close alone does NOT trigger this — only
+// true idleness does — so a task that is mid-flight keeps running in the
+// background after you close the tab, and survives until it finishes.
+// Set IDLE_TIMEOUT_MS=0 to disable idle reclamation entirely (agents live
+// until MAX_AGENT_LIFETIME_MS or server shutdown).
 const IDLE_TIMEOUT_MS = (() => {
   const raw = process.env.IDLE_TIMEOUT_MS;
   if (raw === undefined || raw === "") return 5 * 60 * 1000;
@@ -56,6 +60,30 @@ const IDLE_TIMEOUT_MS = (() => {
   return n;
 })();
 
+// Hard ceiling on how long a background pi agent may live, even if still busy.
+// Protects against runaway agents that never terminate. 0 = unlimited.
+const MAX_AGENT_LIFETIME_MS = (() => {
+  const raw = process.env.MAX_AGENT_LIFETIME_MS;
+  if (raw === undefined || raw === "") return 30 * 60 * 1000; // 30 min
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) {
+    console.warn(`[pi-web-chat] Invalid MAX_AGENT_LIFETIME_MS="${raw}", falling back to 1800000`);
+    return 30 * 60 * 1000;
+  }
+  return n;
+})();
+
+// How many pi->browser events to buffer while no WebSocket is attached, so a
+// reconnecting client can replay what happened in the background after they
+// closed the tab. Ring buffer; oldest events are dropped on overflow.
+const EVENT_BUFFER_SIZE = (() => {
+  const raw = process.env.EVENT_BUFFER_SIZE;
+  if (raw === undefined || raw === "") return 2000;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) return 2000;
+  return n;
+})();
+
 // Maximum number of concurrently-pooled pi RPC subprocesses. New WebSocket
 // connections beyond the cap are rejected with a clear message instead of
 // silently exhausting memory. Set MAX_CONCURRENT_AGENTS=0 to disable.
@@ -77,6 +105,8 @@ const MAX_CONCURRENT_AGENTS = (() => {
 // idle timer, reducing pressure on small-memory hosts. Default: false.
 const IDLE_DROP_HEAP = process.env.IDLE_DROP_HEAP === "1" || process.env.IDLE_DROP_HEAP === "true";
 
+const nowMs = () => Date.now();
+
 // Active pi RPC processes pooled by session key (`${cwd}:${resolvedSessionPath}`)
 const activeAgents = new Map();
 
@@ -90,27 +120,42 @@ class PiAgent {
     this.proc = null;
     this.buffer = "";
     this.alive = false;
-    this.cleanupTimer = null;
+    // lifecycle / background-task state
+    this.state = "idle";            // "idle" | "streaming"
+    this.idleTimer = null;         // true-idle reclamation timer
+    this.lifetimeTimer = null;     // hard max-lifetime kill
+    this.startedAt = 0;
+    this.lastActivityAt = 0;
+    // ring buffer of pi->browser events while no socket is attached, so a
+    // reconnecting client can replay what happened in the background.
+    this.eventBuffer = [];
+    this.bufferHead = 0;
+    // lightweight summary of the task currently running in background, for
+    // the /api/agents dashboard and reconnecting clients.
+    this.lastUserPrompt = null;
   }
 
+  get hasWs() { return this.sockets.size > 0; }
+  get isBusy() { return this.state === "streaming" || this.pending.size > 0; }
+
   attachWs(ws) {
     this.sockets.add(ws);
-    this.cancelCleanup();
+    this.cancelIdleKill();
+    // Replay buffered background events to the newly attached client so it can
+    // catch up on whatever pi produced while no one was watching.
+    this.replayBuffered(ws);
   }
 
   detachWs(ws) {
     this.sockets.delete(ws);
     if (this.sockets.size === 0) {
-      // Keep process alive for IDLE_TIMEOUT_MS so a browser refresh/reconnect
-      // can re-attach to the same pi RPC subprocess. If IDLE_TIMEOUT_MS is 0,
-      // scheduleCleanup still runs but stops the process immediately.
-      const idleMs = IDLE_TIMEOUT_MS === 0 ? 0 : IDLE_TIMEOUT_MS;
-      this.scheduleCleanup(idleMs);
-      if (IDLE_DROP_HEAP && idleMs > 0) {
-        // Give the OS a hint that this process is a candidate for early
-        // reclamation before the idle timer fires. Cheaper than swap pressure.
+      // Browser closed. We do NOT kill the subprocess here: a background task
+      // keeps running. We only arm the idle-kill, which fires once the agent
+      // is truly idle (no streaming, no pending requests) for IDLE_TIMEOUT_MS.
+      if (IDLE_DROP_HEAP) {
         try { if (typeof global.gc === "function") global.gc(); } catch {}
       }
+      this.maybeScheduleIdleKill();
     }
   }
 
@@ -125,32 +170,57 @@ class PiAgent {
     activeAgents.set(key, this);
   }
 
-  scheduleCleanup(delayMs = 300000) {
-    this.cancelCleanup();
-    // delayMs === 0 means "kill the subprocess right now" — used when an
-    // explicit teardown is requested without bypassing the cleanup pipeline.
-    if (delayMs === 0) {
-      console.log(`Cleaning up pi agent immediately (key=${this.sessionKey || "unkeyed"})`);
-      this.stop();
-      return;
-    }
-    this.cleanupTimer = setTimeout(() => {
-      console.log(`Cleaning up inactive pi agent after ${Math.round(delayMs / 1000)}s idle (key=${this.sessionKey || "unkeyed"})`);
-      // One final heap drop just before we kill the subprocess.
+  markActivity() {
+    this.lastActivityAt = nowMs();
+    // any activity cancels a pending idle-kill; it will be re-armed when idle.
+    this.cancelIdleKill();
+    if (!this.hasWs && !this.isBusy) this.maybeScheduleIdleKill();
+  }
+
+  setStreaming(streaming) {
+    this.state = streaming ? "streaming" : "idle";
+    this.markActivity();
+  }
+
+  maybeScheduleIdleKill() {
+    // Only arm the reclamation timer when: no client attached AND truly idle.
+    // A background task that is still running must never be killed here.
+    if (this.hasWs || this.isBusy) return;
+    if (IDLE_TIMEOUT_MS === 0) return; // disabled
+    this.cancelIdleKill();
+    const ms = IDLE_TIMEOUT_MS;
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null;
+      // re-check at fire time — a reconnect or new task may have started.
+      if (this.hasWs || this.isBusy) return;
+      console.log(`Reclaiming truly-idle pi agent after ${Math.round(ms / 1000)}s (key=${this.sessionKey || "unkeyed"})`);
       if (IDLE_DROP_HEAP) {
         try { if (typeof global.gc === "function") global.gc(); } catch {}
       }
       this.stop();
-    }, delayMs);
+    }, ms);
   }
 
-  cancelCleanup() {
-    if (this.cleanupTimer) {
-      clearTimeout(this.cleanupTimer);
-      this.cleanupTimer = null;
+  cancelIdleKill() {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
     }
   }
 
+  // Back-compat shim for any caller that used the old name.
+  scheduleCleanup(delayMs = 300000) {
+    this.cancelIdleKill();
+    if (delayMs === 0) { this.stop(); return; }
+    // treat as immediate idle-kill after the given delay only if truly idle
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null;
+      if (this.hasWs || this.isBusy) return;
+      this.stop();
+    }, delayMs);
+  }
+  cancelCleanup() { this.cancelIdleKill(); }
+
   start() {
     const args = [PI_BIN, "--mode", "rpc", "--session-dir", SESSIONS_DIR];
     this.proc = spawn(args[0], args.slice(1), {
@@ -158,6 +228,14 @@ class PiAgent {
       env: { ...process.env, PI_SKIP_VERSION_CHECK: "1" },
     });
     this.alive = true;
+    this.startedAt = nowMs();
+    this.lastActivityAt = this.startedAt;
+    if (MAX_AGENT_LIFETIME_MS > 0) {
+      this.lifetimeTimer = setTimeout(() => {
+        console.warn(`pi agent hit MAX_AGENT_LIFETIME_MS (${Math.round(MAX_AGENT_LIFETIME_MS / 1000)}s), force-stopping (key=${this.sessionKey || "unkeyed"})`);
+        this.stop();
+      }, MAX_AGENT_LIFETIME_MS);
+    }
     this.proc.on("error", (err) => {
       this.alive = false;
       console.error(`[pi spawn error]`, err);
@@ -176,6 +254,8 @@ class PiAgent {
       if (this.sessionKey) activeAgents.delete(this.sessionKey);
       for (const s of this.sockets) { try { s.close(); } catch {} }
       this.sockets.clear();
+      this.cancelIdleKill();
+      if (this.lifetimeTimer) { clearTimeout(this.lifetimeTimer); this.lifetimeTimer = null; }
     });
   }
 
@@ -199,13 +279,52 @@ class PiAgent {
     if (obj.data?.sessionFile) {
       this.setSessionKey(this.cwd, obj.data.sessionFile);
     }
+    // Track streaming lifecycle so background tasks are not killed mid-flight.
+    switch (obj.type) {
+      case "agent_start": this.setStreaming(true); break;
+      case "agent_end": this.setStreaming(false); break;
+      case "agent_settled": this.setStreaming(false); break;
+      case "pi_exit": this.state = "idle"; break;
+    }
+    // Capture the most recent user prompt for the background-task dashboard.
+    if (obj.type === "remote_user_prompt" || obj.type === "remote_user_steer") {
+      this.lastUserPrompt = { text: obj.message, isSteer: !!obj.isSteer, at: nowMs() };
+    }
     // RPC responses carry `id`; events do not.
     if (obj.type === "response" && obj.id) {
       const res = this.pending.get(obj.id);
       if (res) { this.pending.delete(obj.id); res(obj); }
+      this.markActivity();
     }
-    // Forward every event / response to the browser as-is.
+    // Forward every event / response to connected browsers as-is.
     this.wsSend(obj);
+    // If nobody is listening, remember it so a reconnect can replay.
+    if (!this.hasWs) this.bufferEvent(obj);
+  }
+
+  bufferEvent(obj) {
+    if (EVENT_BUFFER_SIZE <= 0) return;
+    if (this.eventBuffer.length < EVENT_BUFFER_SIZE) {
+      this.eventBuffer.push(obj);
+    } else {
+      this.eventBuffer[this.bufferHead] = obj;
+      this.bufferHead = (this.bufferHead + 1) % EVENT_BUFFER_SIZE;
+    }
+  }
+
+  replayBuffered(ws) {
+    if (this.eventBuffer.length === 0) return;
+    if (ws.readyState !== 1) return;
+    const count = this.eventBuffer.length;
+    // Send a marker so the client knows the next burst is backfill, not live.
+    try { ws.send(JSON.stringify({ type: "backfill_start", count })); } catch {}
+    const start = count === EVENT_BUFFER_SIZE ? this.bufferHead : 0;
+    for (let i = 0; i < count; i++) {
+      const idx = (start + i) % EVENT_BUFFER_SIZE;
+      const ev = this.eventBuffer[idx];
+      try { ws.send(JSON.stringify(ev)); } catch {}
+    }
+    try { ws.send(JSON.stringify({ type: "backfill_end", streaming: this.isBusy, state: this.state })); } catch {}
   }
 
   send(cmd) {
@@ -214,11 +333,13 @@ class PiAgent {
       const id = String(++this.reqId);
       const payload = { ...cmd, id };
       this.pending.set(id, resolve);
+      this.markActivity();
       this.proc.stdin.write(JSON.stringify(payload) + "\n");
       // Safety: timeout so a dropped response doesn't leak the promise.
       setTimeout(() => {
         if (this.pending.has(id)) {
           this.pending.delete(id);
+          this.markActivity();
           resolve({ type: "response", id, success: false, error: "timeout" });
         }
       }, 60000);
@@ -227,25 +348,50 @@ class PiAgent {
 
   sendNoReply(cmd) {
     if (!this.alive) throw new Error("pi process not alive");
+    this.markActivity();
     this.proc.stdin.write(JSON.stringify(cmd) + "\n");
   }
 
   wsSend(obj, excludeSocket = null) {
     const payload = typeof obj === "string" ? obj : JSON.stringify(obj);
-    for (const ws of this.sockets) {
+    for (const ws of [...this.sockets]) {
+      if (ws.readyState > 1) { // CLOSING or CLOSED
+        this.sockets.delete(ws);
+        continue;
+      }
       if (ws !== excludeSocket && ws.readyState === 1) {
         try {
           ws.send(payload);
         } catch (e) {
           console.error("wsSend error", e);
+          this.sockets.delete(ws);
         }
       }
     }
   }
 
+  status() {
+    return {
+      cwd: this.cwd,
+      sessionKey: this.sessionKey,
+      alive: this.alive,
+      state: this.state,
+      busy: this.isBusy,
+      hasClients: this.hasWs,
+      clientCount: this.sockets.size,
+      pendingRequests: this.pending.size,
+      startedAt: this.startedAt || null,
+      lastActivityAt: this.lastActivityAt || null,
+      uptimeMs: this.startedAt ? nowMs() - this.startedAt : 0,
+      bufferedEvents: this.eventBuffer.length,
+      lastUserPrompt: this.lastUserPrompt,
+    };
+  }
+
   stop() {
     this.alive = false;
-    this.cancelCleanup();
+    this.cancelIdleKill();
+    if (this.lifetimeTimer) { clearTimeout(this.lifetimeTimer); this.lifetimeTimer = null; }
     if (this.sessionKey) {
       activeAgents.delete(this.sessionKey);
     }
@@ -291,6 +437,17 @@ app.get("/api/validate-dir", async (req, res) => {
   }
 });
 
+// Endpoint listing all live background pi agents (for dashboards / debug).
+// Shows which sessions are still running headlessly after the browser closed.
+app.get("/api/agents", (req, res) => {
+  const agents = [];
+  for (const [key, a] of activeAgents.entries()) {
+    if (!a.alive) continue;
+    agents.push({ key, ...a.status() });
+  }
+  res.json({ count: agents.length, idleTimeoutMs: IDLE_TIMEOUT_MS, maxLifetimeMs: MAX_AGENT_LIFETIME_MS, agents });
+});
+
 // Scan SESSIONS_DIR for .jsonl files in BOTH the root AND every subdirectory.
 // Why both? Because pi stores sessions under a cwd-encoded subdir (e.g.
 // `--home-zrlgs--`) when left to its own device, but our server passes
@@ -317,6 +474,47 @@ async function listAllSessionFiles() {
   return files;
 }
 
+// Memory metadata cache keyed by file path -> { mtimeMs, cwd, sessionInfo }
+const sessionMetadataCache = new Map();
+
+async function getSessionMetadata(file) {
+  const fileStat = await stat(file);
+  const cached = sessionMetadataCache.get(file);
+  if (cached && cached.mtimeMs === fileStat.mtimeMs) {
+    return cached;
+  }
+
+  const content = await readFile(file, "utf8");
+  const lines = content.split("\n").filter(Boolean);
+  let header = null, title = null, msgCount = 0;
+  for (const line of lines) {
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    if (o.type === "session") header = o;
+    if (o.type === "message" && o.message && o.message.role === "user" && !title) {
+      title = extractText(o.message.content).slice(0, 80);
+    }
+    if (o.type === "message") msgCount++;
+  }
+
+  if (!header) return null;
+
+  const result = {
+    mtimeMs: fileStat.mtimeMs,
+    cwd: normalizeCwd(header.cwd),
+    sessionInfo: {
+      file,
+      name: path.basename(file),
+      id: header.id,
+      timestamp: header.timestamp,
+      firstUser: title,
+      messageCount: msgCount,
+    },
+  };
+  sessionMetadataCache.set(file, result);
+  return result;
+}
+
 app.get("/api/sessions", async (req, res) => {
   try {
     const cwd = normalizeCwd(req.query.cwd);
@@ -324,27 +522,10 @@ app.get("/api/sessions", async (req, res) => {
     const sessions = [];
     for (const full of all) {
       try {
-        const content = await readFile(full, "utf8");
-        const lines = content.split("\n").filter(Boolean);
-        let header = null, title = null, msgCount = 0;
-        for (const line of lines) {
-          let o;
-          try { o = JSON.parse(line); } catch { continue; }
-          if (o.type === "session") header = o;
-          if (o.type === "message" && o.message && o.message.role === "user" && !title) {
-            title = extractText(o.message.content).slice(0, 80);
-          }
-          if (o.type === "message") msgCount++;
+        const meta = await getSessionMetadata(full);
+        if (meta && meta.cwd === cwd) {
+          sessions.push(meta.sessionInfo);
         }
-        if (!header || normalizeCwd(header.cwd) !== cwd) continue;
-        sessions.push({
-          file: full,
-          name: path.basename(full),
-          id: header.id,
-          timestamp: header.timestamp,
-          firstUser: title,
-          messageCount: msgCount,
-        });
       } catch {}
     }
     sessions.sort((a, b) => (b.timestamp || "").localeCompare(a.timestamp || ""));
@@ -526,6 +707,7 @@ wss.on("connection", (ws, req) => {
       case "prompt":
         // Sync prompt to other connected clients in the same session
         agent.wsSend({ type: "remote_user_prompt", message: msg.message, images: msg.images }, ws);
+        agent.lastUserPrompt = { text: msg.message, isSteer: false, at: nowMs() };
         agent.send({ type: "prompt", message: msg.message, images: msg.images });
         break;
       case "abort":
@@ -541,6 +723,7 @@ wss.on("connection", (ws, req) => {
       case "steer":
         // Sync steer instruction to other connected clients in the same session
         agent.wsSend({ type: "remote_user_prompt", message: msg.message, isSteer: true }, ws);
+        agent.lastUserPrompt = { text: msg.message, isSteer: true, at: nowMs() };
         agent.send({ type: "steer", message: msg.message });
         break;
       case "set_session_name":
@@ -576,3 +759,22 @@ wss.on("connection", (ws, req) => {
     }
   });
 });
+
+// ---- Graceful shutdown: stop all background pi agents on exit ----
+function shutdownAllAgents(reason) {
+  console.log(`\n[pi-web-chat] ${reason}: stopping ${activeAgents.size} background pi agent(s)…`);
+  for (const a of [...activeAgents.values()]) {
+    try { a.stop(); } catch {}
+  }
+  clearInterval(heartbeatInterval);
+  try { wss.close(); } catch {}
+  try { httpServer.close(); } catch {}
+}
+process.on("SIGINT", () => { shutdownAllAgents("SIGINT"); process.exit(0); });
+process.on("SIGTERM", () => { shutdownAllAgents("SIGTERM"); process.exit(0); });
+process.on("exit", () => {
+  // best-effort: kill any still-living children synchronously on hard exit
+  for (const a of activeAgents.values()) {
+    try { a.proc && a.proc.kill("SIGKILL"); } catch {}
+  }
+});