agentus 0.3.0 → 0.3.2

package/NOTICE

@@ -1,9 +1,14 @@
 Agentus
 Copyright 2026 Agentus contributors
 
-This product includes code derived from AionUi (https://github.com/iOfficeAI/AionUi),
-licensed under the Apache License 2.0. Derivations are marked with SPDX file headers
-where applicable.
+Licensed under the Apache License, Version 2.0 — see LICENSE. Third-party components
+keep their own licences.
+
+AionUi (https://github.com/iOfficeAI/AionUi) is credited as an INSPIRATION. Its
+published design notes and the behaviour of its interfaces were studied while Agentus
+was designed, and some of our choices follow them. No AionUi source code was copied:
+every implementation in this repository is Agentus's own, and no file carries an
+AionUi licence header because none needs one.
 
 The Hermes and Qoder brand marks under packages/web/public/coding-agents/ are the
 respective property of their owners (EKKOLearnAI / Alibaba). They are included

package/README.md

@@ -24,7 +24,7 @@ agents: open several sessions in the browser, each one backed by a real
 ```bash
 # public one-liner — the published package (Node >= 22.5; the store is node:sqlite)
 npx agentus                      # …or: npm i -g agentus, then `agentus`
-# open http://localhost:8787 and log in (admin / 123456 — see "Login" below),
+# open http://localhost:8788 and log in (admin / 123456 — see "Login" below),
 # then "+ new session", pick a backend + a working directory
 ```
 
@@ -102,7 +102,7 @@ layer never changes.
 
 | var | default | meaning |
 |---|---|---|
-| `AGENTUS_PORT` | `8787` | server port (never reads bare `PORT` — that name is polluted on shared hosts) |
+| `AGENTUS_PORT` | `8788` | server port (never reads bare `PORT` — that name is polluted on shared hosts) |
 | `AGENTUS_DATA` | `~/.agentus` | where state lives; see "Where your state lives" for the full order (`<repo>/packages/server/.data` on a checkout that already has one) |
 | `AGENTUS_HERMES_CMD` | `hermes` | binary to spawn for the hermes backend |
 | `AGENTUS_QODER_CMD` | `~/.local/bin/qodercli` | ditto for qoder |
@@ -196,7 +196,7 @@ Auth environment:
 ### Exposing it publicly (tunnel / reverse proxy)
 
 Put `AGENTUS_BASIC_AUTH=:pass` in the server's environment, then point the tunnel at
-`<lan-ip>:8787`. That gives you two independent locks — Basic at the edge of the app, the
+`<lan-ip>:8788`. That gives you two independent locks — Basic at the edge of the app, the
 operator login inside it — and scripts can still get in (`curl -u :pass` plus the machine
 token).
 
@@ -231,7 +231,7 @@ Two things to know about a tunnel in front of this app:
 #### TLS: a second listener, on purpose
 
 A plain TCP tunnel (SakuraFrp, safe-nat, `ssh -L`, most frp setups) forwards bytes — it
-does **not** terminate TLS for you. Point one at `:8787` and the operator's password and
+does **not** terminate TLS for you. Point one at `:8788` and the operator's password and
 session cookie cross the internet in clear text. So the server can speak TLS itself:
 
 ```bash
@@ -242,7 +242,7 @@ scripts/make-cert.sh                    # self-signed, SAN = the name you actual
 
 | port | speaks | for |
 |---|---|---|
-| `AGENTUS_PORT` (8787) | plain HTTP | LAN, loopback, `curl`, scripts — no cert warning, CI unchanged |
+| `AGENTUS_PORT` (8788) | plain HTTP | LAN, loopback, `curl`, scripts — no cert warning, CI unchanged |
 | `AGENTUS_TLS_PORT` (8443) | HTTPS (self-signed) | **the tunnel** — encrypts the public hop |
 
 Same handler, same routes, same auth; only the socket differs. Two listeners beat both

package/README.zh-CN.md

@@ -22,7 +22,7 @@
 ```bash
 # 对外一条命令 —— 用 npm 上发布的包（Node >= 22.5，存储用 node:sqlite）
 npx agentus                      # 或者 npm i -g agentus 然后直接跑 `agentus`
-# 打开 http://localhost:8787，用 admin / 123456 登录（见下面「登录」），
+# 打开 http://localhost:8788，用 admin / 123456 登录（见下面「登录」），
 # 然后「+ 新建会话」，选一个后端和一个工作目录
 ```
 
@@ -93,7 +93,7 @@ npm run agentus               # the same CLI as `npx agentus`, straight from the
 
 | 变量 | 默认值 | 含义 |
 |---|---|---|
-| `AGENTUS_PORT` | `8787` | 服务端口（从不读取裸 `PORT` —— 这个名字在共享主机上被污染） |
+| `AGENTUS_PORT` | `8788` | 服务端口（从不读取裸 `PORT` —— 这个名字在共享主机上被污染） |
 | `AGENTUS_DATA` | `~/.agentus` | 状态所在；完整顺序见「状态放在哪」（已有数据的老 checkout 上是 `<repo>/packages/server/.data`） |
 | `AGENTUS_HERMES_CMD` | `hermes` | hermes 后端要拉起的二进制 |
 | `AGENTUS_QODER_CMD` | `~/.local/bin/qodercli` | qoder 同上 |
@@ -177,7 +177,7 @@ cookie 用 `HttpOnly` 而不是 `localStorage` 里的 token，并且它会顺带
 
 ### 公网暴露（隧道 / 反向代理）
 
-把 `AGENTUS_BASIC_AUTH=:pass` 放进服务端环境，然后把隧道指向 `<lan-ip>:8787`。这样你就有了两把独立
+把 `AGENTUS_BASIC_AUTH=:pass` 放进服务端环境，然后把隧道指向 `<lan-ip>:8788`。这样你就有了两把独立
 的锁 —— 边缘的 Basic，里面的运维者登录 —— 脚本依然能进（`curl -u :pass` 加上机器 token）。
 
 这里推荐只用密码的形式（`:pass`，或裸 `pass`）：HTTP Basic 总是会让浏览器问用户名（RFC 7617 传
@@ -205,7 +205,7 @@ cookie 用 `HttpOnly` 而不是 `localStorage` 里的 token，并且它会顺带
 #### TLS：刻意做成第二个监听器
 
 纯 TCP 隧道（SakuraFrp、safe-nat、`ssh -L`、大多数 frp 配置）只转发字节 —— 它**不会**替你终结 TLS。
-把它指向 `:8787`，运维者的密码和 session cookie 就会以明文穿过互联网。所以服务端可以自己讲 TLS：
+把它指向 `:8788`，运维者的密码和 session cookie 就会以明文穿过互联网。所以服务端可以自己讲 TLS：
 
 ```bash
 scripts/make-cert.sh                    # self-signed, SAN = the name you actually type
@@ -215,7 +215,7 @@ scripts/make-cert.sh                    # self-signed, SAN = the name you actual
 
 | 端口 | 讲什么 | 给谁 |
 |---|---|---|
-| `AGENTUS_PORT` (8787) | 纯 HTTP | LAN、loopback、`curl`、脚本 —— 无证书警告，CI 不变 |
+| `AGENTUS_PORT` (8788) | 纯 HTTP | LAN、loopback、`curl`、脚本 —— 无证书警告，CI 不变 |
 | `AGENTUS_TLS_PORT` (8443) | HTTPS（自签名） | **隧道** —— 加密公网那一跳 |
 
 同一套 handler，同一套路由，同一套认证；只有 socket 不同。两个监听器胜过另外两种做法：把单端口变成

package/bin/agentus.mjs

@@ -2,7 +2,7 @@
 /**
  * `agentus` — the command an npm install gives you.
  *
- *   npx agentus                 # start the cockpit on :8787
+ *   npx agentus                 # start the cockpit on :8788
  *   npx agentus --port 9000     # …somewhere else
  *   npx agentus --data ~/work   # …with its state in a directory you chose
  *   npx agentus --where         # print the resolved paths and exit (nothing starts)
@@ -36,7 +36,7 @@ Usage
   agentus [options]
 
 Options
-  -p, --port <n>     port to listen on                 (AGENTUS_PORT, default 8787)
+  -p, --port <n>     port to listen on                 (AGENTUS_PORT, default 8788)
   -d, --data <dir>   where state lives — sqlite, login, TLS material, settings
                                                        (AGENTUS_DATA, default ~/.agentus)
   -o, --open         open the cockpit in your browser once it is up
@@ -115,7 +115,7 @@ if (opts.port !== undefined) env.AGENTUS_PORT = String(opts.port);
 if (opts.data !== undefined) env.AGENTUS_DATA = opts.data;
 if (opts.where) env.AGENTUS_PRINT_PATHS = "1";
 
-const port = env.AGENTUS_PORT ?? "8787";
+const port = env.AGENTUS_PORT ?? "8788";
 if (!opts.where) {
   console.log(`[agentus] starting — open http://localhost:${port} when it is up (Ctrl-C stops it)`);
 }

package/docs/dev/01-dev-loop.md

@@ -11,7 +11,7 @@ instances:
 | | live | dev |
 |---|---|---|
 | path | `worktrees/agentus` | `worktrees/agentus-dev` |
-| HTTP port | `8787` | `8901` |
+| HTTP port | `8788` | `8901` |
 | TLS port | `8443` | disabled (`AGENTUS_TLS_PORT=0`) |
 | data dir | `<tree>/packages/server/.data` | `/tmp/agentus-qa-account` |
 | started by | `~/.hermes/cache/agentus/launch.py` | `bash scripts/dev.sh start` |
@@ -85,7 +85,7 @@ which one won and why** — a directory change is the thing that would otherwise
 For the worktrees, the outcome is fixed by the launchers rather than by the rules:
 
 - **live** — `~/.hermes/cache/agentus/launch.py` pins `AGENTUS_DATA=<live>/packages/server/.data`
-  and `AGENTUS_PORT=8787`, and pops the inherited QA/DEV keys. The launcher owns its
+  and `AGENTUS_PORT=8788`, and pops the inherited QA/DEV keys. The launcher owns its
   identity; it never trusts `os.environ`.
 - **dev** — `scripts/dev.sh` exports `AGENTUS_DATA=/tmp/agentus-qa-account` and
   `AGENTUS_PORT=8901`.

package/docs/dev/03-release.md

@@ -75,7 +75,7 @@ If `<slug>` is omitted, the branch name is used with `/` → `-`. What it does:
 | start shape | `scripts/start.sh`, `package.json` |
 | stale launcher | the live process is still running under `tsx watch` |
 
-5. If a restart is needed, calls `scripts/relaunch.sh --port 8787 --tree <live>
+5. If a restart is needed, calls `scripts/relaunch.sh --port 8788 --tree <live>
    --launcher <live launcher>`, which TERMs the process group, waits for the port to free,
    starts the launcher, polls `/healthz`, and **asserts the pid changed** (a failure exits
    non-zero, so "built fine, still serving old code" cannot pass).
@@ -92,7 +92,7 @@ are all required:
 - `no server-side change` printed,
 - the **asset hash moved** (`web asset: <before> -> <after>`; `promote` warns if web sources
   changed but the hash did not),
-- the **pid did NOT move** (`lsof -ti:8787` unchanged — a moved pid means it took the
+- the **pid did NOT move** (`lsof -ti:8788` unchanged — a moved pid means it took the
   restart branch and the release was not the kind it claimed to be).
 
 `package.json` is a restart trigger, so **any** edit to it — even one new npm alias for a QA
@@ -145,15 +145,15 @@ curl -s --noproxy '*' -H "Authorization: Bearer $TOK" http://127.0.0.1:8901/api/
 hash. `promote` echoes it; you can also read it directly:
 
 ```bash
-curl -s --noproxy '*' http://127.0.0.1:8787/api/version
+curl -s --noproxy '*' http://127.0.0.1:8788/api/version
 ```
 
 **3. Grep the served bundle for the new markers.** Fetch the real vite-named file
 (`assets/index-<hash>.js`) and look for a string only the new code has:
 
 ```bash
-HASH=$(curl -s --noproxy '*' http://127.0.0.1:8787/api/version | ...)
-curl -s --noproxy '*' "http://127.0.0.1:8787/assets/$HASH.js" | grep -c '<new-marker>'
+HASH=$(curl -s --noproxy '*' http://127.0.0.1:8788/api/version | ...)
+curl -s --noproxy '*' "http://127.0.0.1:8788/assets/$HASH.js" | grep -c '<new-marker>'
 ```
 
 Two traps: the file is `index-<hash>.js`, so a check that fetches `/assets/<hash>.js`

package/docs/dev/04-recover.md

@@ -23,13 +23,13 @@ empty. Triage the identity, not the liveness (see "Is it serving the wrong store
 
 | port | who |
 |---|---|
-| `8787` | live HTTP |
+| `8788` | live HTTP |
 | `8443` | live TLS (public tunnel points here) |
 | `8901` | dev / QA instance |
 | `8648` | **Hermes Studio** — not Agentus, do not touch |
 
 ```bash
-lsof -nP -iTCP:8787 -sTCP:LISTEN        # who owns the port (returns the CHILD, not the supervisor)
+lsof -nP -iTCP:8788 -sTCP:LISTEN        # who owns the port (returns the CHILD, not the supervisor)
 ps -o pid,ppid,pgid,command -p <pid>    # its process group and command line
 ```
 
@@ -82,7 +82,7 @@ file at that same path, and its server was the only way into the machine. Rules:
    `spawn(..., { detached: true })` and kill the process group — rather than cleaning up by
    name afterwards.
 5. **Re-check the neighbours afterwards:** one `curl` per resident service
-   (`:8648` Studio, `:8787`/`:8443` live, `:8901` dev). A cleanup that leaves the box worse
+   (`:8648` Studio, `:8788`/`:8443` live, `:8901` dev). A cleanup that leaves the box worse
    than it found it is the whole failure mode.
 
 ## The SQLite store, WAL, and the `*.bak` files
@@ -127,7 +127,7 @@ running slot was reaped — yet the port answers 200 and `/api/version` looks fi
 `AGENTUS_DATA`/`AGENTUS_PORT` and pops the QA/DEV keys, but verify identity directly:
 
 ```bash
-PID=$(lsof -nP -iTCP:8787 -sTCP:LISTEN -t)
+PID=$(lsof -nP -iTCP:8788 -sTCP:LISTEN -t)
 ps eww -p "$PID" | tr ' ' '\n' | grep AGENTUS          # the process's own identity vars
 lsof -p "$PID" | grep sqlite                           # which store it actually opened
 ```
@@ -137,11 +137,17 @@ Recovery:
 ```bash
 cd worktrees/agentus
 env -u AGENTUS_DATA -u AGENTUS_BASE -u DEV_LOG_PATH -u DEV_PROMOTE_DETACHED -u DEV_PROMOTE_SELF \
-  bash scripts/relaunch.sh --port 8787 --launcher ~/.hermes/cache/agentus/launch.py
+  bash scripts/relaunch.sh --port 8788 --launcher ~/.hermes/cache/agentus/launch.py \
+    --launchd ai.hermes.agentus
 TOK=$(cat packages/server/.data/auth.token)
-curl -s -X POST -H "Authorization: Bearer $TOK" http://127.0.0.1:8787/api/sessions/<id>/resume
+curl -s -X POST -H "Authorization: Bearer $TOK" http://127.0.0.1:8788/api/sessions/<id>/resume
 ```
 
+`--launchd <label>` makes relaunch.sh hand the restart to launchd (`kickstart -k`) rather than
+killing the process by hand — once the job is installed, a hand-kill is not a restart, it is a
+respawn race (launchd brings the old process back while our own launcher starts a second one). Pass
+it whenever the label is loaded; relaunch.sh ignores it when it is not.
+
 After any restart, put the operator back on the air: `POST /api/sessions/<id>/resume` with the
 machine token → `status: ready` and a fresh pid. **Capture the slot ids to resume before the
 restart** — in the window right after a restart a slot has dropped from `live` into
@@ -155,8 +161,8 @@ one-click problem. Endpoints behind the login:
 
 ```bash
 TOK=$(cat <DATA_DIR>/auth.token)
-curl -s -H "Authorization: Bearer $TOK" http://127.0.0.1:8787/api/auth/locked-ips
-curl -s -X DELETE -H "Authorization: Bearer $TOK" http://127.0.0.1:8787/api/auth/locked-ips
+curl -s -H "Authorization: Bearer $TOK" http://127.0.0.1:8788/api/auth/locked-ips
+curl -s -X DELETE -H "Authorization: Bearer $TOK" http://127.0.0.1:8788/api/auth/locked-ips
 ```
 
 In the UI it is Settings → 登录失败锁定 (which IPs are locked, for how long, unlock / unlock

package/docs/dev/README.md

@@ -20,12 +20,35 @@ variables, and they must never touch each other's code or data:
 |---|---|---|
 | tree | `worktrees/agentus` | `worktrees/agentus-dev` |
 | role | the instance the operator actually uses | where changes are made and tested |
-| HTTP port | `8787` | `8901` |
+| HTTP port | `8788` | `8901` |
 | TLS port | `8443` | off (`AGENTUS_TLS_PORT=0`) |
 | data dir | `<tree>/packages/server/.data` (pinned by the launcher) | `/tmp/agentus-qa-account` |
 | launcher | `~/.hermes/cache/agentus/launch.py` | `scripts/dev.sh start\|stop\|status\|logs` |
+| supervision | launchd job `ai.hermes.agentus` (`KeepAlive`) | none — a plain detached process |
 | hot reload | **no** — restart is explicit | yes (`tsx watch`) |
 
+**Ports are configuration, not literals.** Both of live's ports live in
+`~/.hermes/cache/agentus/ports.env`; `launch.py` pins them into the server's environment, and
+`scripts/dev.sh` / `scripts/relaunch.sh` read the same file instead of hardcoding a number. Move
+live by editing that one line and restarting it — never by hunting a literal through the launchers,
+the scripts and the docs (that is how the port and the TLS port both drifted before).
+
+**Live is supervised by launchd.** It used to be a detached child of whatever shell happened to
+start it: nothing brought it back after a crash, and it inherited that shell's entire environment
+(usually an agent session's, handing `HERMES_SESSION_ID` and `WEIXIN_TOKEN` down to every ACP child
+it spawned). Now:
+
+```bash
+launchctl print gui/$(id -u)/ai.hermes.agentus         # state, pid, the job's environment
+launchctl kickstart -k gui/$(id -u)/ai.hermes.agentus  # the supported restart (stop then start)
+tail -f /tmp/agentus-server.log                        # the job's stdout/stderr
+```
+
+`scripts/relaunch.sh --launchd ai.hermes.agentus` is the same thing wrapped with a health check and
+a pid-moved assertion, and that is what `promote` uses. Launchd's `KeepAlive` restarts it on any
+exit, so a crash self-heals; a **manual** `kill` therefore no longer restarts live, it just makes
+launchd respawn it.
+
 **Why two trees.** `tsx watch` reloads the whole server on any server-source edit, and a
 reload SIGTERMs every child process — every live `hermes acp` session, including the one
 the operator is typing into. Editing server code in the live tree would therefore kill his

package/docs/installation.md

@@ -91,7 +91,7 @@ serves once (no watcher). `AGENTUS_PORT=9000 npm start` moves the port.
 ```
 agentus [options]
 
-  -p, --port <n>     port to listen on                 (AGENTUS_PORT, default 8787)
+  -p, --port <n>     port to listen on                 (AGENTUS_PORT, default 8788)
   -d, --data <dir>   where state lives (sqlite, login, TLS material, settings)
                                                        (AGENTUS_DATA, default ~/.agentus)
   -o, --open         open the cockpit in your browser once it is up
@@ -107,7 +107,7 @@ answer to "where did my data go" (see below).
 ## First run
 
 1. Start it: `agentus` (or `npx agentus`, or `npm start` from a checkout).
-2. Open **http://localhost:8787** and log in. Default credentials:
+2. Open **http://localhost:8788** and log in. Default credentials:
 
    ```
    username: admin
@@ -130,7 +130,7 @@ unless the backend row names another one — see [HERMES_HOME](#hermes_home).
 
 | var | default | meaning |
 |---|---|---|
-| `AGENTUS_PORT` | `8787` | server port (never reads bare `PORT`) |
+| `AGENTUS_PORT` | `8788` | server port (never reads bare `PORT`) |
 | `AGENTUS_DATA` | `~/.agentus` | where state lives; see [Data directory](#data-directory) |
 | `AGENTUS_HERMES_CMD` | `hermes` | binary to spawn for the hermes backend |
 | `AGENTUS_QODER_CMD` | `~/.local/bin/qodercli` | ditto for qoder |
@@ -189,7 +189,7 @@ with it.
 
 | port | speaks | for |
 |---|---|---|
-| `AGENTUS_PORT` (8787) | plain HTTP | LAN, loopback, `curl`, scripts — no cert warning, CI unchanged |
+| `AGENTUS_PORT` (8788) | plain HTTP | LAN, loopback, `curl`, scripts — no cert warning, CI unchanged |
 | `AGENTUS_TLS_PORT` (8443) | HTTPS (self-signed) | the tunnel — encrypts the public hop |
 | 5173 | Vite dev server | front-end hot reload, only during `npm run dev` |
 
@@ -268,7 +268,7 @@ a different session list.
   <key>Label</key>          <string>org.agentus.cockpit</string>
   <key>ProgramArguments</key>
   <array>
-    <string>/usr/bin/env</string><string>agentus</string><string>--port</string><string>8787</string>
+    <string>/usr/bin/env</string><string>agentus</string><string>--port</string><string>8788</string>
   </array>
   <key>EnvironmentVariables</key>
   <dict><key>AGENTUS_DATA</key><string>/Users/YOU/.agentus</string></dict>
@@ -293,7 +293,7 @@ Description=Agentus cockpit
 After=network.target
 
 [Service]
-ExecStart=/usr/bin/env agentus --port 8787
+ExecStart=/usr/bin/env agentus --port 8788
 Environment=AGENTUS_DATA=%h/.agentus
 Restart=on-failure
 
@@ -335,7 +335,7 @@ touches `~/.hermes` (your agents' own data) or any working directory.
 ## Troubleshooting
 
 **Port already in use.** `agentus --port 9000`, or find and stop the holder:
-`lsof -nP -iTCP:8787 -sTCP:LISTEN`. Agentus never reads bare `PORT` for exactly this reason.
+`lsof -nP -iTCP:8788 -sTCP:LISTEN`. Agentus never reads bare `PORT` for exactly this reason.
 
 **"No backend" / a session won't start.** The agent CLI is missing or not logged in. Run
 `hermes acp --check`, or `qodercli login` (a `-32000` on `newSession` means qoder is not logged
@@ -362,5 +362,5 @@ requests. The live stream rides on `/ws`; use a tunnel that passes WebSockets th
 TCP+auto-HTTPS tunnels are verified working).
 
 **Certificate warning on the LAN.** That is the TLS listener's self-signed cert (a bare LAN IP
-cannot carry a trusted cert). Either use the plain-HTTP `:8787` port on the LAN, or install the
+cannot carry a trusted cert). Either use the plain-HTTP `:8788` port on the LAN, or install the
 issuer once from `/cert.crt` (see [TLS](#tls)).

package/docs/installation.zh-CN.md

@@ -88,7 +88,7 @@ npm run agentus                     # 与 `npx agentus` 同一个 CLI，直接
 ```
 agentus [options]
 
-  -p, --port <n>     监听端口                        (AGENTUS_PORT，默认 8787)
+  -p, --port <n>     监听端口                        (AGENTUS_PORT，默认 8788)
   -d, --data <dir>   状态目录（sqlite、登录、TLS 材料、设置）
                                                        (AGENTUS_DATA，默认 ~/.agentus)
   -o, --open         就绪后自动在浏览器打开驾驶舱
@@ -103,7 +103,7 @@ agentus [options]
 ## 首次运行
 
 1. 启动：`agentus`（或 `npx agentus`，或 checkout 里的 `npm start`）。
-2. 打开 **http://localhost:8787** 登录。默认凭据：
+2. 打开 **http://localhost:8788** 登录。默认凭据：
 
    ```
    username: admin
@@ -125,7 +125,7 @@ agentus [options]
 
 | 变量 | 默认值 | 含义 |
 |---|---|---|
-| `AGENTUS_PORT` | `8787` | 服务端口（从不读裸 `PORT`） |
+| `AGENTUS_PORT` | `8788` | 服务端口（从不读裸 `PORT`） |
 | `AGENTUS_DATA` | `~/.agentus` | 状态目录；见[数据目录](#数据目录) |
 | `AGENTUS_HERMES_CMD` | `hermes` | hermes 后端要拉起的可执行文件 |
 | `AGENTUS_QODER_CMD` | `~/.local/bin/qodercli` | qoder 后端同理 |
@@ -181,7 +181,7 @@ agentus [options]
 
 | 端口 | 协议 | 用途 |
 |---|---|---|
-| `AGENTUS_PORT`（8787） | 纯 HTTP | 局域网、本机回环、`curl`、脚本 —— 无证书警告，CI 不变 |
+| `AGENTUS_PORT`（8788） | 纯 HTTP | 局域网、本机回环、`curl`、脚本 —— 无证书警告，CI 不变 |
 | `AGENTUS_TLS_PORT`（8443） | HTTPS（自签） | **隧道** —— 加密公网那一跳 |
 | 5173 | Vite 开发服务器 | 前端热更新，仅在 `npm run dev` 期间 |
 
@@ -257,7 +257,7 @@ Agentus 默认在前台跑；一个服务单元能让它跨登录、跨重启常
   <key>Label</key>          <string>org.agentus.cockpit</string>
   <key>ProgramArguments</key>
   <array>
-    <string>/usr/bin/env</string><string>agentus</string><string>--port</string><string>8787</string>
+    <string>/usr/bin/env</string><string>agentus</string><string>--port</string><string>8788</string>
   </array>
   <key>EnvironmentVariables</key>
   <dict><key>AGENTUS_DATA</key><string>/Users/YOU/.agentus</string></dict>
@@ -282,7 +282,7 @@ Description=Agentus cockpit
 After=network.target
 
 [Service]
-ExecStart=/usr/bin/env agentus --port 8787
+ExecStart=/usr/bin/env agentus --port 8788
 Environment=AGENTUS_DATA=%h/.agentus
 Restart=on-failure
 
@@ -323,7 +323,7 @@ rm -rf ~/.agentus                  # 删状态 —— SQLite、登录、TLS 密
 ## 排错
 
 **端口被占用。** 用 `agentus --port 9000`，或找出并停掉占用者：
-`lsof -nP -iTCP:8787 -sTCP:LISTEN`。Agentus 从不读裸 `PORT`，原因正在于此。
+`lsof -nP -iTCP:8788 -sTCP:LISTEN`。Agentus 从不读裸 `PORT`，原因正在于此。
 
 **「没有后端」/ 会话起不来。** 缺少 agent CLI，或它没登录。跑 `hermes acp --check`，或
 `qodercli login`（`newSession` 报 `-32000` 就是 qoder 没登录）。在设置里检查后端行的命令；启动
@@ -347,4 +347,4 @@ rm -rf ~/.agentus                  # 删状态 —— SQLite、登录、TLS 密
 `/ws`；请换成能透传 WebSocket 的隧道（SakuraFrp 的 TCP+auto-HTTPS 隧道已验证可用）。
 
 **局域网里出现证书警告。** 那是 TLS 监听的自签证书（裸局域网 IP 无法承载可信证书）。要么在
-局域网里用纯 HTTP 的 `:8787` 端口，要么从 `/cert.crt` 装一次签发证书（见 [TLS](#tls)）。
+局域网里用纯 HTTP 的 `:8788` 端口，要么从 `/cert.crt` 装一次签发证书（见 [TLS](#tls)）。

package/docs/transcript-folding.md

@@ -131,7 +131,7 @@ And against real data — the one-off used when this landed, on the operator's o
 ```bash
 # rows → the CLIENT's fold, over the operator API
 curl -s -H "Authorization: Bearer $(cat "${AGENTUS_DATA:-$HOME/.agentus}/auth.token")" \
-  'http://127.0.0.1:8787/api/sessions/<id>/messages?tail=1'
+  'http://127.0.0.1:8788/api/sessions/<id>/messages?tail=1'
 ```
 
 Result for `hello`: **3804 rows → 70** (10 agent messages, 15 thought blocks, 37 tool cards, 8 prompts),

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "agentus",
- "version": "0.3.0",
+ "version": "0.3.2",
  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
  "license": "Apache-2.0",
  "repository": {

package/packages/server/src/acp/session-manager.ts

@@ -159,6 +159,12 @@ interface LiveSession {
    *  so a second interrupting utterance that already started its own turn is not mistaken for
    *  "the one I cancelled is still running". */
   turnSeq: number;
+  /** When the operator last USED this slot — he opened it, or his page reported it as the one on
+   *  screen. In memory on purpose: this is the half of the idle rule that says "he was just here",
+   *  and the store's message clock (which survives restarts) is the other half. Reading only the
+   *  message clock reaped a slot he had clicked into a minute earlier (see `touch()` and the clock
+   *  in `startIdleReaper`). */
+  touchedAt: number;
   /** Text sinks for sessions that live on this connection but are NOT the one in the rail —
    *  today only the throwaway fork used to summarise the conversation for a title. Anything
    *  whose sessionId is not `info.acpSessionId` is routed here and never persisted. */
@@ -367,6 +373,10 @@ export class SessionManager {
       child, busy: false, pendingPermissions: new Map(), alwaysAllow: new Set(), stderrBuf: [],
       caps: { fork: false, load: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
       planToken: randomUUID(),
+      // A brand-new process is, by definition, freshly used: the click that spawned it is the
+      // activity. Without this the slot inherits the store's message clock — yesterday's — and the
+      // reaper's first tick after the spawn kills the process the operator just asked for.
+      touchedAt: Date.now(),
       // Until this slot's first PROMPT, anything the agent says is its own history being replayed,
       // not an answer (see #onSessionUpdate). A resumed agent re-sends its whole transcript on
       // `session/load` — full-length blocks, no messageId — and persisting those wrote 1240 rows
@@ -515,6 +525,10 @@ export class SessionManager {
       child, busy: false, pendingPermissions: new Map(), alwaysAllow: new Set(), stderrBuf: [],
       caps: { fork: false, load: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
       planToken: randomUUID(),
+      // A brand-new process is, by definition, freshly used: the click that spawned it is the
+      // activity. Without this the slot inherits the store's message clock — yesterday's — and the
+      // reaper's first tick after the spawn kills the process the operator just asked for.
+      touchedAt: Date.now(),
       // Until this slot's first PROMPT, anything the agent says is its own history being replayed,
       // not an answer (see #onSessionUpdate). A resumed agent re-sends its whole transcript on
       // `session/load` — full-length blocks, no messageId — and persisting those wrote 1240 rows
@@ -1007,7 +1021,7 @@ export class SessionManager {
         command: process.execPath,
         args: [path.join(path.dirname(fileURLToPath(import.meta.url)), "../../mcp/plan-server.mjs")],
         env: [
-          { name: "AGENTUS_PLAN_ENDPOINT", value: `http://127.0.0.1:${process.env.AGENTUS_PORT ?? 8787}` },
+          { name: "AGENTUS_PLAN_ENDPOINT", value: `http://127.0.0.1:${process.env.AGENTUS_PORT ?? 8788}` },
           { name: "AGENTUS_PLAN_TOKEN", value: live.planToken },
           { name: "AGENTUS_PLAN_SESSION", value: live.info.id },
         ],
@@ -1246,6 +1260,22 @@ export class SessionManager {
     this.#sessions.delete(live.info.id);
   }
 
+  /** The operator just USED this slot: he opened it, or his page reported it as the one on screen.
+   *
+   *  Idempotent and cheap — the cockpit reports presence every few seconds, so while a slot is on
+   *  screen this is called continuously and the idle clock never runs out under a conversation he
+   *  is reading; the moment he switches away it stops, and the slot gets the full threshold from
+   *  the last report instead of from its last MESSAGE.
+   *
+   *  Only the in-memory clock moves. `info.lastAt` stays the store's message time on purpose: it is
+   *  what the rail's relative stamps and the "last activity" hint mean, and making it say 刚刚 for a
+   *  session nobody has written to would be the UI lying. */
+  touch(id: string): void {
+    const live = this.#sessions.get(id);
+    if (!live || live.info.status === "closed" || live.info.status === "reaped") return;
+    live.touchedAt = Date.now();
+  }
+
   /** Reclaim idle slots: stop the agent process of a session nobody has touched for the operator's
    *  threshold. Deliberately NOT an archive — the row stays in 工作空间 wearing `reaped` and a click
    *  brings it back. AionUi ships exactly this switch (设置 → 系统 → 「Agent 空闲超时（分钟）」,
@@ -1266,7 +1296,13 @@ export class SessionManager {
         if (s.busy || s.pendingPermissions.size) continue;
         if (s.info.status === "starting" || s.info.status === "running") continue;
         if (opts.watched?.(s.info.id)) continue;
-        const lastAt = s.info.lastAt ?? s.info.createdAt;
+        // The clock is the LATER of two things: the last MESSAGE this session has (store time, which
+        // survives restarts) and the last time the operator actually USED the slot (`touchedAt` — the
+        // click that respawned it, or the page reporting it as the one on screen). Reading only the
+        // message clock is how a slot he had just opened got reaped a minute later (2026-10-10:
+        // 「刚点进去、没发消息、换个会话过一分钟 acp 就被回收」) — the fresh process inherited a
+        // days-old stamp, so the very next tick found it over the threshold.
+        const lastAt = Math.max(s.touchedAt, s.info.lastAt ?? 0, s.info.createdAt);
         if (now - lastAt < idleMs) continue;
         console.log(
           `[agentus] idle reap: ${s.info.id} (${Math.round((now - lastAt) / 60_000)} min idle, limit ${Math.round(idleMs / 60_000)} min)`,
@@ -1287,7 +1323,19 @@ export class SessionManager {
   /** The list every client needs to be current: the rows PLUS what is already waiting for an
    *  answer. Sent on connect too, which is what makes a refreshed page show a live approval. */
   #emitSessions(): void {
-    this.#emit({ t: "sessions", sessions: this.list(), pending: this.pendingPermissions() });
+    // ALL THREE buckets, every time. This is the SAME event the HTTP path builds (`sessionsEvent()`
+    // in index.ts), and the client replaces its lists wholesale from whatever arrives — so emitting
+    // only `sessions` here meant every call site below (a resume, a close, an archive, and the idle
+    // reaper) WIPED the operator's cold and archived rows off the rail until the next full event or
+    // a reload: 「刷新之后只看得见活着的会话」. `cold()`/`archived()` are this class's own lists —
+    // sending them costs nothing and is the only shape the client can safely consume.
+    this.#emit({
+      t: "sessions",
+      sessions: this.list(),
+      cold: this.cold(),
+      archived: this.archived(),
+      pending: this.pendingPermissions(),
+    });
   }
 
   /** Every request currently waiting for an answer, across live sessions. Exists so a page

package/packages/server/src/index.ts

@@ -25,7 +25,7 @@ import * as auth from "./auth.js";
 import { NotifyCenter } from "./notify/center.js";
 import type { BackendId, ClientCommand, PermissionDecision, PromptAttachment, ServerEvent } from "../../shared/src/index.js";
 
-const PORT = Number(process.env.AGENTUS_PORT ?? 8787);
+const PORT = Number(process.env.AGENTUS_PORT ?? 8788);
 // Data + web build resolve against THIS FILE, not the shell's cwd: `scripts/start.sh`
 // launches from the repo root while the dev server runs from packages/server, and a
 // cwd-relative path would silently open a second database (the operator's slots would
@@ -196,6 +196,10 @@ const notify = new NotifyCenter({
   operator: (req, url) => Boolean(auth.authenticate(req.headers, url)),
   // The companion artifact, so the phone panel in 设置 can show its size without a second request.
   apkPath: APK_FILE,
+  // The page reporting which session it is showing is also the idle reaper's clock: opening a slot
+  // (and staying in it) counts as USED, so switching away gives it a full threshold instead of
+  // reaping it on the next tick because its last MESSAGE was days ago.
+  onFocus: (sessionId: string) => mgr.touch(sessionId),
   // Username+password pairing: the phone types the same login the browser uses. The check and
   // its rate limit stay here, in auth.ts, so a phone cannot have a laxer door than the UI.
   credentials: (username, password, ip) => {
@@ -1385,9 +1389,42 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
     return;
   }
   const session = term;
+  // ---- backpressure, half two: OUR OWN socket queue ---------------------------
+  // The page's watermarks (see ToolPanel's TerminalTab) can only count bytes that REACH it;
+  // everything still queued in this process is invisible from there. A slow page plus a fast
+  // producer therefore grows node's send queue without bound — measured on a `yes` flood: ~340 MB
+  // queued in seconds while the page only ever received ~106 frames/s. So the socket's own backlog
+  // is an independent brake, OR-ed with the client's request into one pause state, and the chain it
+  // walks back is the same one: stop reading the child -> the pty helper blocks in write(1) -> the
+  // shell blocks in write(2).
+  const NET_HIGH = 1 << 20; // 1 MiB queued -> stop draining the pty
+  const NET_LOW = 256 * 1024;
+  let clientPaused = false;
+  let socketPaused = false;
+  let paused = false;
+  const applyPause = (): void => {
+    const want = clientPaused || socketPaused;
+    if (want === paused) return;
+    paused = want;
+    if (want) session.pause();
+    else session.resume();
+  };
   const send = (msg: unknown): void => {
-    if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
+    if (ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify(msg));
+    if (!socketPaused && ws.bufferedAmount >= NET_HIGH) {
+      socketPaused = true;
+      applyPause();
+    }
   };
+  // `ws` emits no drain event for its send queue, so the way back up is a cheap poll that only
+  // runs while we are actually holding the pty back.
+  const backlogTimer = setInterval(() => {
+    if (socketPaused && ws.bufferedAmount <= NET_LOW) {
+      socketPaused = false;
+      applyPause();
+    }
+  }, 100);
   // The buffered tail goes out first, so a reconnect (or a second tab) lands on the scrollback the
   // way ttyd's RESUME does instead of a blank screen.
   if (session.buffer) send({ t: "term-data", id: session.id, data: session.buffer });
@@ -1410,12 +1447,20 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
       }
     } else if (cmd.t === "term-resize" && typeof cmd.cols === "number" && typeof cmd.rows === "number") {
       session.resize(cmd.cols, cmd.rows);
+    } else if (cmd.t === "term-pause") {
+      // The page's emulator fell behind: hold the pty so the backlog cannot grow there instead.
+      clientPaused = true;
+      applyPause();
+    } else if (cmd.t === "term-resume") {
+      clientPaused = false;
+      applyPause();
     } else if (cmd.t === "term-close") {
       terms.kill(session.id);
       ws.close();
     }
   });
   const cleanup = (): void => {
+    clearInterval(backlogTimer);
     session.subscribers.delete(onData);
     terms.kill(session.id);
   };