agentus 0.3.3 → 0.3.4

package/README.md

@@ -48,6 +48,11 @@ Hermes on your PATH; `hermes acp --check` self-checks) or `qodercli --acp` (`qod
 first, else `newSession` fails with `-32000`). Without one the cockpit still runs and still
 logs in — you just have no backend to start a session on.
 
+A plain Hermes install drives sessions; the cockpit's own extras — per-session **thinking
+depth**, a permission mode that survives a restart, the **context-budget** field — come from the
+fork's integration build instead. That is a five-line install:
+[§ Which Hermes to run](docs/installation.md#which-hermes-to-run).
+
 The first slot you start will use the Hermes home **your own agent already uses**
 (`~/.hermes`) unless the backend row names another one — see "HERMES_HOME" below.
 
@@ -73,7 +78,7 @@ stale, then serves. Use `AGENTUS_PORT=9000 npm start` to move the port.
 ### Where your state lives
 
 `~/.agentus` by default — `agentus.sqlite` (sessions and transcript), `credentials.json`,
-`auth.token` (the machine credential), `auth.secret`, `tls/`, `settings.json`. It is
+`auth.token` (the machine credential), `auth.secret`, `settings.json`. It is
 created 0700 on first boot, and the boot log prints it **and why that directory won**:
 
 | order | rule |
@@ -111,8 +116,6 @@ layer never changes.
 | `AGENTUS_HISTORY_PAGE` | `500` | transcript page size (also set small in tests to exercise paging) |
 | `AGENTUS_TERM_PTY` | unset | `1` = run the workspace terminal through Python's stdlib `pty` (real tty; needs `python3`) instead of pipes |
 | `AGENTUS_TERM_CMD` | unset | override the terminal command line entirely (e.g. `socat …`), space-separated |
-| `AGENTUS_TLS_PORT` | `8443` when a cert exists, else off | **second listener, TLS** — the one a public tunnel points at (`0` disables it) |
-| `AGENTUS_TLS_CERT` / `AGENTUS_TLS_KEY` | `<AGENTUS_DATA>/tls/{cert,key}.pem` | cert material for that listener (see `scripts/make-cert.sh`) |
 | `AGENTUS_TTS_BASE_URL` | unset | OpenAI-compatible base for **server** speech synthesis (`…/v1`). Unset = browser voices only |
 | `AGENTUS_TTS_API_KEY` / `AGENTUS_TTS_MODEL` / `AGENTUS_TTS_VOICE` | – / `tts-1` / `alloy` | ditto |
 | `AGENTUS_STT_BASE_URL` | unset | OpenAI-compatible base for **server** transcription. Unset = browser recognition only |
@@ -228,57 +231,23 @@ Two things to know about a tunnel in front of this app:
   the session cookie is issued `Secure` automatically (verified through that same tunnel),
   so no config needed. The last hop inside your LAN stays plain HTTP.
 
-#### 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 `:8788` and the operator's password and
-session cookie cross the internet in clear text. So the server can speak TLS itself:
+#### TLS: terminated in front, not in-process
 
-```bash
-scripts/make-cert.sh                    # self-signed, SAN = the name you actually type
-# -> $AGENTUS_DATA/tls/{cert.pem,key.pem} (0600, git-ignored) — ~/.agentus/tls by default
-# boot log then says: https://0.0.0.0:8443 (self-signed …) ; point a tunnel at THIS port
-```
+A plain TCP tunnel (SakuraFrp, safe-nat, `ssh -L`, most frp setups) forwards bytes — it does
+**not** terminate TLS for you. Point one at `:8788` and the operator's password and session
+cookie would cross the internet in clear text. So terminate TLS **in front of Agentus** — a
+reverse proxy (Caddy/nginx) or a tunnel that does its own `public_tls` — and let this process
+speak plain HTTP:
 
 | port | speaks | for |
 |---|---|---|
-| `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
-alternatives: turning the single port into HTTPS would put a cert warning in front of your
-own LAN usage (and break `curl` scripts), while sniffing the first byte on one port to
-serve both hides whether a given visit was really encrypted.
-
-**Retiring the warning on your devices.** With TLS on, the listener serves its own
-certificate at `/cert.crt`:
-
-```bash
-https://<your-name>:<tls-port>/cert.crt     # iOS: opens the profile installer directly
-                                            # Android: downloads it → Settings → Security → CA certificate
-curl --cacert <AGENTUS_DATA>/tls/cert.pem https://<your-name>:<tls-port>/healthz   # scripts, no -k
-```
-
-Installed as a trusted root (iOS also needs *About → Certificate Trust Settings → enable*),
-the browser stops asking and the address bar is clean. It is public material — the private
-key never leaves `<AGENTUS_DATA>/tls/`.
-
-The cert is **self-signed on purpose** — no CA issues for an unregistered domain or a bare
-IP, so the browser shows "not private → proceed" once per device, and installing the issuer
-(`/cert.crt`, above) retires even that. Keep the SAN to the name you type (**the DDNS name**,
-not the public IP: a dynamic IP would need re-issuing, and a mismatch adds a second warning).
-
-`make-cert.sh` issues **two** certs on purpose: a 10-year root (`ca.pem`, what devices
-install) and a 390-day leaf (`cert.pem`, what the listener serves). Apple caps *server
-certificate* validity at 398 days — a 10-year self-signed leaf is precisely what iOS refuses
-*after* the user has been through the install dance. A root is not a server cert, so it can
-live long; rotating the leaf (`--leaf-only`) never touches an installed device.
+| `AGENTUS_PORT` (8788) | plain HTTP | LAN, loopback, `curl`, scripts — no cert warning, CI unchanged; **the only listener** |
 
-`npm run tls-smoke` (in CI, real sockets) guards all of it: a verifying client must be
-*rejected* (that is what proves the port is actually TLS), the leaf must chain to the root
-`/cert.crt` hands out and stay under the 398-day cap, the API login and `wss://…/ws` handshake
-must work over TLS (the upgrade handler is bound to both listeners — the easy thing to
-forget), and the LAN port must stay plain.
+Certificate lifecycle (issuing, rotation, SAN) stays in that front layer and never touches the
+app, and the LAN path stays warning-free. Nothing is lost on the cookie side either: the handler
+reads `X-Forwarded-Proto` (`packages/server/src/auth.ts`), so a request that arrived over TLS at
+the front layer still gets a `Secure` session cookie — Caddy and nginx both set that header by
+default.
 
 Logout revokes the session id server-side, so "sign out" ends the session instead of
 just hiding the UI — the cookie stops working immediately.
@@ -449,7 +418,6 @@ npm run auth-smoke                        # 48 assertions: the lock, both creden
 npm run backend-smoke                     # 42: the backend registry, spawn env, health evidence
 npm run workspace-smoke                   # 85: workspace field, file API, shell, attachments
 npm run voice-smoke                       # 47: settings/theme guards, voice router, 百炼 shapes
-npm run tls-smoke                         # the second listener, real sockets + real certs
 npm run package-smoke                     # packs, installs into a throwaway prefix + HOME, boots
                                           # that install, drives a mock turn, checks ~/.agentus
 node scripts/smoke.mjs mock "hello"       # end-to-end against the mock agent

package/README.zh-CN.md

@@ -43,6 +43,10 @@ web bundle、配套 APK —— 然后直接退出，不启动任何东西）。
 可自检）或 `qodercli --acp`（先 `qodercli login`，否则 `newSession` 会以 `-32000` 失败）。没有它驾驶舱
 照样能跑、照样能登录 —— 只是没有后端可以开会话。
 
+裸装的 Hermes 就能跑会话；驾驶舱自己的那几项能力 —— 按会话切换的**思考深度**、跨重启存活的**权限模式**、
+**上下文预算**输入框 —— 来自 fork 的集成构建（tag）。装法就五行：
+[§ 该跑哪份 Hermes](docs/installation.zh-CN.md#该跑哪份-hermes)。
+
 你启动的第一个 slot 会使用**你自己的 agent 已经在用的**那个 Hermes home（`~/.hermes`），除非后端那一行
 指定了另一个 —— 见下面的「HERMES_HOME」。
 
@@ -66,7 +70,7 @@ npm run agentus               # the same CLI as `npx agentus`, straight from the
 ### 状态放在哪
 
 默认 `~/.agentus` —— 里面有 `agentus.sqlite`（会话与 transcript）、`credentials.json`、`auth.token`
-（机器凭证）、`auth.secret`、`tls/`、`settings.json`。首次启动时以 0700 创建，启动日志会打印它**以及
+（机器凭证）、`auth.secret`、`settings.json`。首次启动时以 0700 创建，启动日志会打印它**以及
 这个目录获胜的原因**：
 
 | 顺序 | 规则 |
@@ -102,8 +106,6 @@ npm run agentus               # the same CLI as `npx agentus`, straight from the
 | `AGENTUS_HISTORY_PAGE` | `500` | transcript 分页大小（测试里也会调小以覆盖分页路径） |
 | `AGENTUS_TERM_PTY` | 未设置 | `1` = 工作区终端走 Python 标准库 `pty`（真 tty；需要 `python3`）而不是管道 |
 | `AGENTUS_TERM_CMD` | 未设置 | 完全覆盖终端命令行（例如 `socat …`），空格分隔 |
-| `AGENTUS_TLS_PORT` | 存在证书时 `8443`，否则关闭 | **第二个监听器，TLS** —— 公网隧道指向的那个（`0` 关闭它） |
-| `AGENTUS_TLS_CERT` / `AGENTUS_TLS_KEY` | `<AGENTUS_DATA>/tls/{cert,key}.pem` | 该监听器的证书材料（见 `scripts/make-cert.sh`） |
 | `AGENTUS_TTS_BASE_URL` | 未设置 | **服务端**语音合成的 OpenAI 兼容 base（`…/v1`）。未设置 = 只用浏览器语音 |
 | `AGENTUS_TTS_API_KEY` / `AGENTUS_TTS_MODEL` / `AGENTUS_TTS_VOICE` | – / `tts-1` / `alloy` | 同上 |
 | `AGENTUS_STT_BASE_URL` | 未设置 | **服务端**转写的 OpenAI 兼容 base。未设置 = 只用浏览器识别 |
@@ -202,50 +204,19 @@ cookie 用 `HttpOnly` 而不是 `localStorage` 里的 token，并且它会顺带
 - **在边缘终结 TLS。** 当请求带着 `X-Forwarded-Proto: https` 到达时，session cookie 会自动以 `Secure`
   下发（在同一隧道上实测过），所以无需配置。你 LAN 内的最后一跳仍然是纯 HTTP。
 
-#### TLS：刻意做成第二个监听器
+#### TLS：在前置层终结，而不是在进程内
 
 纯 TCP 隧道（SakuraFrp、safe-nat、`ssh -L`、大多数 frp 配置）只转发字节 —— 它**不会**替你终结 TLS。
-把它指向 `:8788`，运维者的密码和 session cookie 就会以明文穿过互联网。所以服务端可以自己讲 TLS：
-
-```bash
-scripts/make-cert.sh                    # self-signed, SAN = the name you actually type
-# -> $AGENTUS_DATA/tls/{cert.pem,key.pem} (0600, git-ignored) — ~/.agentus/tls by default
-# boot log then says: https://0.0.0.0:8443 (self-signed …) ; point a tunnel at THIS port
-```
+把它指向 `:8788`，运维者的密码和 session cookie 就会以明文穿过互联网。所以要在 Agentus **前面**终结
+TLS：放一层反代（Caddy / nginx），或者用自带 `public_tls` 的隧道；本进程自己只讲纯 HTTP：
 
 | 端口 | 讲什么 | 给谁 |
 |---|---|---|
-| `AGENTUS_PORT` (8788) | 纯 HTTP | LAN、loopback、`curl`、脚本 —— 无证书警告，CI 不变 |
-| `AGENTUS_TLS_PORT` (8443) | HTTPS（自签名） | **隧道** —— 加密公网那一跳 |
-
-同一套 handler，同一套路由，同一套认证；只有 socket 不同。两个监听器胜过另外两种做法：把单端口变成
-HTTPS 会把证书警告挡在你自己 LAN 的使用前面（并弄坏 `curl` 脚本），而在一个端口上嗅探首字节来同时服
-务两者会掩盖一次访问到底有没有被加密。
-
-**在你的设备上退掉那个警告。** 开着 TLS 时，监听器在 `/cert.crt` 提供自己的证书：
-
-```bash
-https://<your-name>:<tls-port>/cert.crt     # iOS: opens the profile installer directly
-                                            # Android: downloads it → Settings → Security → CA certificate
-curl --cacert <AGENTUS_DATA>/tls/cert.pem https://<your-name>:<tls-port>/healthz   # scripts, no -k
-```
-
-装成受信任的根证书后（iOS 还需要 *关于 → 证书信任设置 → 启用*），浏览器就不再追问，地址栏也就干净了。
-它是公开材料 —— 私钥永远不离开 `<AGENTUS_DATA>/tls/`。
-
-证书是**刻意自签名**的 —— 对一个未注册的域名或裸 IP，没有 CA 会签发，所以浏览器每台设备显示一次「不
-是私密连接 → 继续」，而装上签发者（`/cert.crt`，见上）连这个都能退掉。把 SAN 保持为你实际输入的名字
-（**DDNS 名**，而不是公网 IP：动态 IP 会需要重签，而名字不匹配会多一个警告）。
-
-`make-cert.sh` 刻意签发**两张**证书：一张 10 年根证书（`ca.pem`，设备装的就是它）和一张 390 天的叶子
-证书（`cert.pem`，监听器提供的就是它）。Apple 把*服务器证书*有效期上限定在 398 天 —— 一张 10 年的自
-签名叶子证书恰恰是 iOS 在用户走完那套安装流程*之后*会拒绝的东西。根证书不是服务器证书，所以可以活得
-久；轮换叶子证书（`--leaf-only`）永远不碰已经装好的设备。
+| `AGENTUS_PORT` (8788) | 纯 HTTP | LAN、loopback、`curl`、脚本 —— 无证书警告，CI 不变；**唯一的监听** |
 
-`npm run tls-smoke`（在 CI 里，真 socket）守着这一切：一个做校验的客户端必须被*拒绝*（这才证明该端口
-真的是 TLS），叶子证书必须能链到根证书、且 `/cert.crt` 发出的就是它、并保持在 398 天上限内，API 登录
-和 `wss://…/ws` 握手必须能在 TLS 上工作（升级 handler 绑定在两个监听器上 —— 这是最容易忘的地方），而
-LAN 端口必须保持明文。
+证书的生命周期（签发、轮换、SAN）留在前置层里，永远不碰应用；LAN 这条路也就没有证书警告。cookie 这边
+也没有损失：handler 读 `X-Forwarded-Proto`（`packages/server/src/auth.ts`），所以凡是在前置层走了 TLS
+的请求，照样下发 `Secure` 的 session cookie —— Caddy 和 nginx 默认都会带上这个头。
 
 登出会在服务端撤销 session id，所以「登出」是结束会话，而不只是藏起 UI —— cookie 立刻失效。
 
@@ -373,7 +344,6 @@ npm run auth-smoke                        # 48 assertions: the lock, both creden
 npm run backend-smoke                     # 42: the backend registry, spawn env, health evidence
 npm run workspace-smoke                   # 85: workspace field, file API, shell, attachments
 npm run voice-smoke                       # 47: settings/theme guards, voice router, 百炼 shapes
-npm run tls-smoke                         # the second listener, real sockets + real certs
 npm run package-smoke                     # packs, installs into a throwaway prefix + HOME, boots
                                           # that install, drives a mock turn, checks ~/.agentus
 node scripts/smoke.mjs mock "hello"       # end-to-end against the mock agent

package/bin/agentus.mjs

@@ -14,8 +14,8 @@
  * package alike, so `npm i -g agentus` never needs a compiler on the user's machine.
  *
  * WHY `--where` RUNS THE SERVER instead of computing paths here: where the data lives is
- * decided in exactly one place (`packages/server/src/index.ts`, mirrored by
- * scripts/make-cert.sh). A second implementation here would be a second answer to "where
+ * decided in exactly one place (`packages/server/src/index.ts`). A second
+ * implementation here would be a second answer to "where
  * did my sessions go" — the one question in this project that must never have two
  * answers. With AGENTUS_PRINT_PATHS=1 the server prints its own resolution (data dir,
  * web bundle, companion APK, node version) and exits before it opens anything.
@@ -37,14 +37,14 @@ Usage
 
 Options
   -p, --port <n>     port to listen on                 (AGENTUS_PORT, default 8788)
-  -d, --data <dir>   where state lives — sqlite, login, TLS material, settings
+  -d, --data <dir>   where state lives — sqlite, login, settings
                                                        (AGENTUS_DATA, default ~/.agentus)
   -o, --open         open the cockpit in your browser once it is up
       --where        print the resolved paths and exit (starts nothing)
   -h, --help         this text
   -v, --version      print the version
 
-The server reads more environment variables than these (agent backends, auth, TLS,
+The server reads more environment variables than these (agent backends, auth,
 speech). They are listed in the README, and the boot log prints the ones in play.
 
 Requirements

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

@@ -12,7 +12,6 @@ instances:
 |---|---|---|
 | path | `worktrees/agentus` | `worktrees/agentus-dev` |
 | 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` |
 | watcher | no (one process, no reload) | yes (`tsx watch`) |
@@ -101,7 +100,7 @@ live. Two independent knobs if you need more:
 - **The store** — override `AGENTUS_DATA` (as `dev.sh` does). A throwaway instance is one
   line:
   ```bash
-  AGENTUS_PORT=8907 AGENTUS_TLS_PORT=0 AGENTUS_DATA=/tmp/<name> npx tsx packages/server/src/index.ts
+  AGENTUS_PORT=8907 AGENTUS_DATA=/tmp/<name> npx tsx packages/server/src/index.ts
   ```
   Note the server reads `AGENTUS_PORT`, not bare `PORT` — and this box exports an ambient
   `PORT=8648` (Hermes Studio), so a script that reads the ambient value starts a retry loop

package/docs/dev/02-verify.md

@@ -36,7 +36,6 @@ node scripts/auth-smoke.mjs                              # the lock, both creden
 node scripts/backend-registry-smoke.mjs                  # backend registry, spawn env, health (~42)
 node scripts/workspace-smoke.mjs                         # workspace, file API, shell, attachments (~85)
 node scripts/voice-smoke.mjs                             # settings/theme guards, voice router (~47)
-npm run tls-smoke                                        # the TLS listener, real sockets + real certs
 npm run package-smoke                                    # pack + install into a throwaway HOME + boot
 node scripts/smoke.mjs mock "hello"                      # end-to-end against the mock agent
 ```

package/docs/dev/04-recover.md

@@ -6,13 +6,12 @@ I fix it without making the box worse?
 ## Read the boot log first
 
 The boot log is the authoritative account of what the server resolved. It prints **which
-data directory won and why**, the auth state, and the TLS listener:
+data directory won and why** and the auth state:
 
 ```
 data dir: /Users/…/packages/server/.data  (AGENTUS_DATA was set)      ← the dir + the reason
 auth on: user "admin"
-https://0.0.0.0:8443 (self-signed …)                                  ← present = TLS listener up
-tls off: no cert at <DATA_DIR>/tls/cert.pem                           ← absent/off = no TLS
+http port: 8788                                                       ← the only listener
 ```
 
 If the directory it names is not the one you expected, stop here — a server serving the
@@ -24,7 +23,6 @@ empty. Triage the identity, not the liveness (see "Is it serving the wrong store
 | port | who |
 |---|---|
 | `8788` | live HTTP |
-| `8443` | live TLS (public tunnel points here) |
 | `8901` | dev / QA instance |
 | `8648` | **Hermes Studio** — not Agentus, do not touch |
 
@@ -82,14 +80,14 @@ 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, `:8788`/`:8443` live, `:8901` dev). A cleanup that leaves the box worse
+   (`:8648` Studio, `:8788` 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
 
 State lives in `<DATA_DIR>/agentus.sqlite` (the transcript and every other row), accessed
 through Node's built-in `node:sqlite` (hence Node `>= 22.5`). Files beside it: `credentials.json`,
-`auth.token`, `auth.secret`, `sessions.json`, `settings.json`, `tls/` — several of them
+`auth.token`, `auth.secret`, `sessions.json`, `settings.json` — several of them
 `0600`. The server creates the directory `0700` on first boot.
 
 **Back up before you touch the store.** A single write against the operator's real data gets
@@ -121,8 +119,8 @@ Two cautions that come from real incidents:
 ## Is it serving the wrong store?
 
 Symptoms that look like separate bugs but share one cause: the operator's session list came
-back empty, TLS silently turned off (`tls off: no cert at <QA_DIR>/tls/cert.pem`), and a
-running slot was reaped — yet the port answers 200 and `/api/version` looks fine. Cause:
+back empty and a running slot was reaped — yet the port answers 200 and `/api/version` looks
+fine. Cause:
 `relaunch → launch.py` inherited the QA environment. The launcher now pins its own
 `AGENTUS_DATA`/`AGENTUS_PORT` and pops the QA/DEV keys, but verify identity directly:
 
@@ -172,24 +170,6 @@ all). Tunables: `AGENTUS_LOGIN_MAX_FAILS` (default 5) / `AGENTUS_LOGIN_LOCK_MS`
 every other session; `AGENTUS_AUTH=off` disables the login entirely and the boot log scolds
 you (do not leave it off — the listener is `0.0.0.0` and this cockpit is tunnelled).
 
-## TLS certificate regeneration
-
-The TLS listener runs on a **second port** (8443 live), pointed at by a plain-TCP tunnel.
-Cert material lives at `<DATA_DIR>/tls/`. Regenerate with:
-
-```bash
-scripts/make-cert.sh [name]        # default name: the DDNS name; SAN = that name + localhost + 127.0.0.1
-scripts/make-cert.sh --leaf-only   # rotate the leaf only; installed devices are untouched
-```
-
-`make-cert.sh` issues **two** certs on purpose: a 10-year root (`ca.pem`, what devices install
-once, served at `/cert.crt`) and a 390-day leaf (`cert.pem`/`key.pem`, what the listener
-serves, under Apple's 398-day cap). Keep the SAN to the DDNS name you actually type, not the
-dynamic public IP. It writes into the same directory the server reads from (mirroring the
-server's own resolution in `packages/server/src/index.ts`), and if that resolution and the
-server's ever diverge the listener stays silently off with a cert sitting next to it — after
-regenerating, confirm the boot log still prints `https://…:8443`.
-
 ## The process-exit safety net for children
 
 The server installs `SIGINT`/`SIGTERM`/`SIGHUP` handlers that terminate the child agent

package/docs/dev/05-agent-driven.md

@@ -38,7 +38,7 @@ agent four things and it can work without guessing.
 | auth | `packages/server/src/auth.ts` |
 | web app | `packages/web/src/App.tsx`, `state.ts`, `transcript.ts` |
 | mock agent (dev/QA) | `packages/server/mock/agent.mjs` |
-| dev launcher | `scripts/dev.sh` · release: `scripts/relaunch.sh` · `scripts/make-cert.sh` |
+| dev launcher | `scripts/dev.sh` · release: `scripts/relaunch.sh` |
 
 **2. The reference implementation to compare against.** Almost every UI question has a
 sibling project that already answered it, and the operator expects behaviour parity, not

package/docs/dev/README.md

@@ -21,17 +21,16 @@ 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 | `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
+**Ports are configuration, not literals.** Live's port lives in
+`~/.hermes/cache/agentus/ports.env`; `launch.py` pins it 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).
+the scripts and the docs (that is how the port 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
@@ -84,5 +83,5 @@ the one exception is a strictly web-only change, and even that is bounded by wha
   notification contract.
 - [`docs/refs/`](../refs/) — notes on the reference UIs and ACP rules this project borrows
   behaviour from.
-- [`README.md`](../../README.md) — install, environment variables, login, TLS and the
+- [`README.md`](../../README.md) — install, environment variables, login and the
   public tunnel.

package/docs/installation.md

@@ -30,6 +30,62 @@ nvm install 22 && nvm use 22      # or
 brew install node                 # or https://nodejs.org/en/download
 ```
 
+### Which Hermes to run
+
+Plain Hermes is enough to drive sessions. The capabilities this cockpit itself leans on are **not**
+in the released build — a per-session **thinking depth** (ACP `reasoning_effort`), a **permission
+mode that survives a restart** and `session/load`, and a free-form **context budget** (with
+256K/512K/768K/1M presets). They live on the ACP branches of the fork
+[`LiangYang666/hermes-agent`](https://github.com/LiangYang666/hermes-agent), and reach the cockpit
+through one **tag per integration build**, in a namespace of its own:
+
+```
+agentus/<hermes version>/merge-<YYYYMMDD-HHMM>
+```
+
+A tag and not a branch, on purpose: the branch of the same name (under `yl-dev/`) is the working
+ref and gets rebuilt, while a tag never moves — so pin the tag. The `agentus/` prefix also keeps
+ours apart from upstream's own tags (`v0.21.7`, `v0.21.7+canary.*`), and the timestamp in the
+last segment sorts, so "newest" is a `sort -V`.
+
+Install Hermes normally first — its installer brings the Python/Node runtime and puts `hermes` on
+your PATH — then run that build on top of that runtime:
+
+```bash
+# 1. Hermes itself: the runtime the slots will use
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+
+# 2. the newest integration build, as a tag (`refs/tags/` spelled out: never ambiguous)
+TAG=$(git ls-remote --tags --refs https://github.com/LiangYang666/hermes-agent.git \
+      'refs/tags/agentus/*' | awk '{print $2}' | sed 's#refs/tags/##' | sort -V | tail -1)
+git clone --depth=1 --branch "$TAG" https://github.com/LiangYang666/hermes-agent.git ~/Project/hermes-agent
+
+# 3. wrap it, and point the cockpit at the wrapper
+mkdir -p ~/.local/bin
+cat > ~/.local/bin/hermes-acp-src <<'WRAP'
+#!/bin/sh
+exec env PYTHONPATH="$HOME/Project/hermes-agent" hermes "$@"
+WRAP
+chmod +x ~/.local/bin/hermes-acp-src
+AGENTUS_HERMES_CMD=~/.local/bin/hermes-acp-src npm start
+```
+
+`PYTHONPATH` puts the checkout **ahead of** the installed package, while the installed runtime still
+supplies the interpreter and its dependencies — which is why step 1 is not optional. Verify what a
+slot will actually run (the same check Agentus suggests when a backend is missing):
+
+```bash
+PYTHONPATH=~/Project/hermes-agent hermes acp --check     # → Hermes ACP check OK
+```
+
+For a service install, put `AGENTUS_HERMES_CMD` in the environment you hand the server — see
+"Running it as a service". Leaving it at the default (`hermes`) keeps a plain install working, so
+the fork is an upgrade, never a requirement.
+
+Moving to a newer build is a fetch + checkout in that same tree — `git fetch --depth=1 origin tag
+<tag> && git checkout <tag>` — not a reinstall; a running slot picks it up the next time it
+restarts.
+
 ## Install
 
 ### One command — the published package (public)
@@ -92,7 +148,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 8788)
-  -d, --data <dir>   where state lives (sqlite, login, TLS material, settings)
+  -d, --data <dir>   where state lives (sqlite, login, settings)
                                                        (AGENTUS_DATA, default ~/.agentus)
   -o, --open         open the cockpit in your browser once it is up
       --where        print the resolved paths and exit (starts nothing)
@@ -101,7 +157,7 @@ agentus [options]
 ```
 
 `--where` is worth knowing: it prints what the server actually resolved — data dir, web bundle,
-companion APK, TLS listener, Node version — and exits before anything starts. It is the one
+companion APK, Node version — and exits before anything starts. It is the one
 answer to "where did my data go" (see below).
 
 ## First run
@@ -137,9 +193,6 @@ unless the backend row names another one — see [HERMES_HOME](#hermes_home).
 | `AGENTUS_HERMES_HOME` | `~/.hermes` | default `HERMES_HOME` for a row that does not name one |
 | `AGENTUS_PERM_TIMEOUT_MS` | `300000` (5 min) | how long a permission prompt waits before auto-cancelling |
 | `AGENTUS_HISTORY_PAGE` | `500` | transcript page size |
-| `AGENTUS_TLS_PORT` | `8443` when a cert exists, else off | the TLS listener (`0` disables it) |
-| `AGENTUS_TLS_CERT` / `AGENTUS_TLS_KEY` | `<DATA_DIR>/tls/{cert,key}.pem` | cert material for that listener |
-| `AGENTUS_TLS_CA` | `<DATA_DIR>/tls/ca.pem` | the root a device installs once |
 | `AGENTUS_TTS_BASE_URL` | unset | OpenAI-compatible base for server speech synthesis (`…/v1`); unset = browser voices only |
 | `AGENTUS_TTS_API_KEY` / `AGENTUS_TTS_MODEL` / `AGENTUS_TTS_VOICE` | – / `tts-1` / `alloy` | ditto |
 | `AGENTUS_STT_BASE_URL` | unset | OpenAI-compatible base for server transcription; unset = browser recognition only |
@@ -167,7 +220,7 @@ wins; the env is what makes a fresh install work before anyone opens it.
 ### Data directory
 
 `~/.agentus` by default. It holds `agentus.sqlite` (sessions + transcript), `credentials.json`,
-`auth.token`, `auth.secret`, `tls/`, `settings.json`. It is created `0700` on first boot, and the
+`auth.token`, `auth.secret`, `settings.json`. It is created `0700` on first boot, and the
 boot log prints it **and why that directory won**:
 
 | order | rule |
@@ -182,18 +235,17 @@ boot it once with `AGENTUS_DATA=~/.agentus`. `agentus --where` prints what the s
 instead of making you guess.
 
 Nothing ever writes inside `node_modules`: for an installed package, `<pkg>/packages/server/.data`
-would be deleted by the next `npm i -g agentus`, taking the transcript, the login and the TLS key
-with it.
+would be deleted by the next `npm i -g agentus`, taking the transcript and the login with it.
 
 ### Ports
 
 | port | speaks | for |
 |---|---|---|
-| `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 |
+| `AGENTUS_PORT` (8788) | plain HTTP | LAN, loopback, `curl`, scripts — no cert warning, CI unchanged; **the only listener** |
 | 5173 | Vite dev server | front-end hot reload, only during `npm run dev` |
 
-Same handler, same routes, same auth on both listeners; only the socket differs.
+TLS is terminated **in front of** this process (a reverse proxy, or a tunnel that does its own
+`public_tls`) — see [TLS](#tls).
 
 ### Login
 
@@ -212,23 +264,16 @@ file wins. Delete `credentials.json` to fall back to the environment.
 ### TLS
 
 A plain TCP tunnel (SakuraFrp, `ssh -L`, most frp setups) forwards bytes — it does not terminate
-TLS for you. So the server can speak TLS itself, on a **second** listener:
-
-```bash
-scripts/make-cert.sh                    # self-signed root + short-lived leaf, SAN = the name you type
-# -> $AGENTUS_DATA/tls/{ca.pem,cert.pem,key.pem}   (key 0600, git-ignored)
-# boot log then says: https://0.0.0.0:8443 (self-signed …) ; point a tunnel at THIS port
-```
+TLS for you. So terminate TLS **in front of** the server: a reverse proxy (Caddy, nginx), or a
+tunnel that does its own `public_tls`.
 
-The listener also serves its own issuer at `/cert.crt`, so a device can install the root once:
-`https://<your-name>:<tls-port>/cert.crt`. iOS opens the profile installer directly; Android
-downloads it (Settings → Security → CA certificate); iOS also needs *About → Certificate Trust
-Settings → enable*. It is public material — the private key never leaves `<DATA_DIR>/tls/`.
+This process listens on plain HTTP only, on purpose: the LAN path then needs no certificate and
+`curl`/scripts stay unchanged, and certificate lifecycle (issuing, rotation, SAN) lives in that
+front layer instead of inside the app.
 
-`make-cert.sh` issues two certs on purpose: a 10-year root (`ca.pem`, what devices install) and a
-390-day leaf (`cert.pem`, what the listener serves). Apple caps server-certificate validity at 398
-days, so a 10-year leaf is exactly what iOS refuses *after* the install dance. Rotate the leaf
-(`--leaf-only`) freely; the installed root is untouched.
+The session cookie still comes out `Secure` when the request arrived over TLS: the handler reads
+`X-Forwarded-Proto` (`packages/server/src/auth.ts`), so any front layer that sets it — Caddy and
+nginx both do by default — gets a `Secure` cookie with no configuration here.
 
 ### Backends
 
@@ -326,7 +371,7 @@ session cookies once instead of logging every device out.
 
 ```bash
 npm rm -g agentus                  # remove the program (state stays)
-rm -rf ~/.agentus                  # remove state — SQLite, login, TLS key, settings
+rm -rf ~/.agentus                  # remove state — SQLite, login, settings
 ```
 
 If you installed into a per-user prefix, `npm rm -g --prefix ~/.local agentus`. Uninstalling never
@@ -361,6 +406,7 @@ them, e.g. `AGENTUS_DATA=~/.agentus agentus` or `AGENTUS_DATA=<repo>/packages/se
 requests. The live stream rides on `/ws`; use a tunnel that passes WebSockets through (SakuraFrp
 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 `:8788` port on the LAN, or install the
-issuer once from `/cert.crt` (see [TLS](#tls)).
+**Certificate warning on the LAN.** The server itself speaks plain HTTP on `:8788`, so a warning
+means you are reaching a TLS-terminating front layer directly by IP — its certificate names a
+domain, not an IP. Either use the plain-HTTP `:8788` port on the LAN, or reach the front layer by
+the name its certificate was issued for.