agentus 0.3.1 → 0.3.3

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`
@@ -195,6 +195,19 @@ git branch --set-upstream-to=origin/main main
 Judge the outcome by identity, not by "the push succeeded": `git ls-remote origin
 refs/heads/main` must equal the commit live is actually serving.
 
+> **Do not merge into the live tree before promoting.** `promote` decides whether to restart by
+> diffing **the live tree's old tip** against the commit it is promoting. If the live tree already
+> sits on that commit (e.g. someone ran `git merge --ff-only <dev-branch>` inside
+> `worktrees/agentus`), the diff is empty: promote prints `no server-side change`, ships the new web
+> bundle, and **leaves the old server process running** — a half release that looks green. Restart
+> detection is only as good as the tree it reads, so move `main` through the ref (`git push
+> origin <dev-branch>:main`), never by checking it out in the live worktree.
+>
+> If it already happened: the release is not done. Re-run the restart explicitly
+> (`scripts/relaunch.sh --port <live> --tree <live tree> --launcher <launcher> --launchd <label>`)
+> and then resume the slots promote captured, exactly as promote's step 6 would have. Prove it by
+> the startup log line for the new feature, not by the pid alone.
+
 ## Rollback
 
 The release path has no separate rollback mechanism — you revert the change and promote

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.1",
+ "version": "0.3.3",
  "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": {
@@ -64,12 +64,12 @@
   "store-fold": "tsx scripts/qa/store-fold.mts",
   "live-stream": "tsx scripts/qa/live-stream.mts",
   "open-target": "tsx scripts/qa/open-target.mts",
- "rail-recent": "tsx scripts/qa/rail-recent.mts",
- "turn-pulse": "tsx scripts/qa/turn-pulse.mts",
- "resume-tail": "tsx scripts/qa/resume-tail.mts",
- "render-lag-sweep": "node scripts/qa/render-lag-sweep.mjs",
- "replay-window": "node scripts/qa/replay-window.mjs",
- "think-cadence": "node scripts/qa/think-cadence.mjs"
+  "rail-recent": "tsx scripts/qa/rail-recent.mts",
+  "turn-pulse": "tsx scripts/qa/turn-pulse.mts",
+  "resume-tail": "tsx scripts/qa/resume-tail.mts",
+  "render-lag-sweep": "node scripts/qa/render-lag-sweep.mjs",
+  "replay-window": "node scripts/qa/replay-window.mjs",
+  "think-cadence": "node scripts/qa/think-cadence.mjs"
  },
  "engines": {
   "node": ">=22.5"

package/packages/server/mock/agent.mjs

@@ -7,6 +7,10 @@
 //   MOCK_TOOL=1        -> prompt triggers a tool_call + requestPermission
 //   MOCK_THINK=1       -> emits agent_thought_chunk before the answer
 //   MOCK_SLOW_MS=n     -> delay between chunks (default 60)
+//   MOCK_SPAWN_MS=n    -> boot latency before the handshake answers (default 0). A real agent takes
+//                         seconds to come up (node + initialize + session/load) and that window is
+//                         where the cockpit's 「正在唤醒 agent 进程…」 state lives — a browser sweep
+//                         cannot observe a state that lasts 80 ms.
 //   MOCK_SINK=1        -> exit the process mid-turn (crash path for AC5/QA)
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
@@ -14,6 +18,10 @@ import { AgentSideConnection, RequestError, ndJsonStream } from "@agentclientpro
 import { Readable, Transform, Writable } from "node:stream";
 
 const SLOW = Number(process.env.MOCK_SLOW_MS || 60);
+/** Boot latency — deliberately BEFORE the stream is wired, so the slot sits in `starting` for as
+ *  long as QA asks. Defaults to 0: the mock is instant unless a sweep needs the wake window. */
+const SPAWN_MS = Number(process.env.MOCK_SPAWN_MS || 0);
+if (SPAWN_MS > 0) await new Promise((r) => setTimeout(r, SPAWN_MS));
 
 // The file a `[tool-diff]` turn pretends to edit: hermes hands the cockpit the whole file
 // before and after, so the approval surface has a path and a real change to show.