@turmind/halo 1.5.4 → 1.5.6

package/bundled-docs/guide/channels/acp.md

@@ -54,6 +54,8 @@ halo acp \
 | `--token` | yes | Web-channel token. `full` access required for multi-workspace use |
 | `--workspace` | yes | Absolute server-side path for this adapter |
 | `--agent-id` | no | Halo agent profile to use when ACP `session/new` creates a fresh session. Default `default` (alias `--agent`) |
+| `--scheme` | no | `http` (default) or `https` — use `https` for a server behind a TLS reverse proxy |
+| `--header "Name: value"` | no | Repeatable. Extra HTTP header sent on every request (like `curl -H`), for auth in front of the server — proxy cookie, `CF-Access-*`, basic auth |
 
 Each adapter process binds to **one** workspace. To drive multiple workspaces concurrently from one token, run multiple adapter processes — one per workspace.
 
@@ -139,7 +141,7 @@ For now: if you want the agent to see a Mac-side file, paste it into the prompt.
 | `401` on first prompt | Token typo, or token was deleted from admin |
 | `403` when launching with `--workspace /some/other/path` | Token is `readonly` / `workspace` access — use a `full` token or omit `--workspace` |
 | Tool calls don't appear in Claude Code | Expected — halo doesn't translate every event back as ACP `tool_call`. See [docs/dev/acp-adapter.md](../../dev/acp-adapter.md) for the full mapping |
-| Two `session/prompt` calls on the same id, second hangs | Halo queues messages when a session is busy; ACP adapter ends the response with `[queued]`. Wait for the first to finish |
+| Two `session/prompt` calls on the same id, second hangs | Halo queues messages when a session is busy; ACP adapter ends the response with `[queued — session busy]`. Wait for the first to finish |
 | `/workspace switch <path>` worked but other tokens broke | You changed the db-level default. Switch back with another `/workspace switch`, or stop using slash commands from the adapter |
 
 ## Reference

package/bundled-docs/guide/channels/feishu.md

@@ -77,16 +77,16 @@ After approval the bot is visible in your Feishu tenant. Repeat this step **ever
 
 ## Step 7 — Add the account in halo admin
 
-Open halo admin → **Channels** → **Feishu** → **Add Account**:
+Open halo admin → **Channels** → **Feishu** → **Add Bot**:
 
 | Field | Value |
 |---|---|
 | App ID | from Step 2 |
 | App Secret | from Step 2 |
-| Verification token | leave blank (long-connect doesn't use it) |
-| Encrypt key | leave blank (long-connect doesn't encrypt the wire) |
-| Workspace path | absolute path, e.g. `/home/ubuntu/my-project` |
-| Label | optional |
+| Verification Token (optional) | leave blank (long-connect doesn't use it) |
+| Encrypt Key (optional) | leave blank (long-connect doesn't encrypt the wire) |
+| Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | a label for the account |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` |
 
@@ -109,7 +109,7 @@ In Feishu desktop / mobile:
 1. Top-bar search → type the bot's name → click into the bot's profile → start a DM → send `hello` → expect a streamed reply
 2. Add the bot to a group: open a group → 设置 → 群机器人 → add → `@halo hi` → expect a reply
 
-If nothing happens, check halo server logs (`/tmp/halo-server.log`) for `[feishu]` lines.
+If nothing happens, check halo server logs (`~/.halo/global/logs/server.log`) for `[Feishu]` lines.
 
 ## How halo handles inbound
 
@@ -117,18 +117,20 @@ If nothing happens, check halo server logs (`/tmp/halo-server.log`) for `[feishu
 - **Groups** — only `@`-mentions wake the bot up
 - **Threads** — Feishu's `root_id` is used as the session boundary; replies stay in-thread
 - **Files** — images go to the LLM as multimodal content; other files are saved under `<workspace>/.halo/assets/feishu/inbound/<accountId>/<date>/`
+- **After a server restart** — if the agent was mid-task when halo restarted, its reply still reaches the most recent 1:1 DM the bot talked in; group threads reconnect on their next `@`-mention
 - **Self-loop** — bot-authored events are dropped to prevent the bot replying to itself
 
 ## Slash commands
 
-Same set as the other channels — type as plain text in a DM or thread:
+Same set as the other channels — type as plain text, **in a 1:1 DM only** (in a group the text goes to the agent as a normal message):
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Feishu
@@ -145,12 +147,12 @@ Search depends on the contact and `im:chat:readonly` scopes from Step 4. If auto
 
 | Symptom | Cause / fix |
 |---|---|
-| `99991663` on Add Account | App Secret wrong — copy it again from Step 2 |
-| `99991668` on Add Account | Bot capability not enabled — go back to Step 3 |
+| `99991663` on Add Bot | App Secret wrong — copy it again from Step 2 |
+| `99991668` on Add Bot | Bot capability not enabled — go back to Step 3 |
 | Bot exists but receives no events | Step 5 mode is set to webhook (not long-connect), or Step 6 wasn't done |
 | Permission errors when sending images / reading group info | New scope was approved but app version wasn't republished — go to Step 6 |
 | Can't find the bot in Feishu search | Step 6 wasn't done. Search results are tenant-wide and only show **published** apps |
-| Multiple halo instances reply to the same message | Only one process should hold the long-connect. Check `~/.halo/global/server.pid` for the lock |
+| Multiple halo instances reply to the same message | Only one process should hold the long-connect. Check `~/.halo/global/server.lock` for the lock |
 
 ## Multi-tenant setup
 

package/bundled-docs/guide/channels/slack.md

@@ -83,14 +83,14 @@ In the Slack desktop client, fully quit and reopen (or `Cmd+R` to reload) — ot
 
 ## Step 7 — Add the account in halo admin
 
-Open halo admin → **Channels** → **Slack** → **Add Account**:
+Open halo admin → **Channels** → **Slack** → **Add Bot**:
 
 | Field | Value |
 |---|---|
-| Bot token | the `xoxb-…` from Step 5 |
-| App token | the `xapp-…` from Step 2 |
-| Workspace path | absolute path to the workspace this bot drives, e.g. `/home/ubuntu/my-project` |
-| Label | optional, e.g. "Engineering bot" |
+| Bot Token (xoxb-…) | the `xoxb-…` from Step 5 |
+| App Token (xapp-…) | the `xapp-…` from Step 2 |
+| Bind to workspace | absolute path to the workspace this bot drives, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | e.g. "Engineering bot" |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` |
 
@@ -111,7 +111,7 @@ Pick the level with that in mind:
 1. In Slack, click the bot's name in the sidebar to start a DM → type `hello` → expect a streamed reply
 2. Invite the bot into a channel: `/invite @halo` → mention it: `@halo what files are in this workspace?` → expect a reply in the same thread
 
-If nothing happens, check the halo server logs (`/tmp/halo-server.log`) for `[slack]` lines.
+If nothing happens, check the halo server logs (`~/.halo/global/logs/server.log`) for `[Slack]` lines.
 
 ## How halo handles inbound
 
@@ -119,18 +119,20 @@ If nothing happens, check the halo server logs (`/tmp/halo-server.log`) for `[sl
 - **Channels / groups** — only `@`-mentions wake the bot up, plain messages are ignored
 - **Threads** — the bot replies in-thread; one halo session per thread, so a long thread stays in one conversation
 - **Files** — images go to the LLM as multimodal content; other files are saved under `<workspace>/.halo/assets/slack/inbound/<accountId>/<date>/`
+- **After a server restart** — if the agent was mid-task when halo restarted, its reply still reaches the most recent conversation (DM or thread) the bot talked in (one per bot); other threads reconnect on their next message
 - **`bot_id` self-loop** — messages posted by any bot (including this one) are dropped, so the agent can't reply to itself
 
 ## Slash commands
 
-Same set as the other channels — type these as plain text in a DM or thread:
+Same set as the other channels, but **only in a DM with the bot** — in a channel or thread the text goes to the agent as a normal message. Slack's own client intercepts a leading `/`, so type `!` instead (e.g. `!session list`); halo treats `!cmd` as `/cmd` and shows `!…` in its replies. The table below uses `/`:
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Slack
@@ -149,10 +151,10 @@ The search depends on the `users:read` / `channels:read` scopes added in Step 4.
 |---|---|
 | **"向此应用发送消息的功能已关闭"** banner on the DM page | Step 6 wasn't done — open App Home, enable Messages Tab, reload Slack |
 | Account created but no events arrive | Socket Mode token (`xapp-`) is wrong, or `connections:write` scope missing on it |
-| `not_authed` / `invalid_auth` error on Add Account | Bot token (`xoxb-`) typo, or you pasted the App token in the Bot field by mistake |
+| `not_authed` / `invalid_auth` error on Add Bot | Bot token (`xoxb-`) typo, or you pasted the App token in the Bot field by mistake |
 | Bot replies to itself in a loop | Should never happen — halo drops all `bot_id`-tagged messages. If it does, file a bug |
 | Search dropdown empty in cron form | Missing `users:read` / `channels:read` scopes — add them, then Reinstall to Workspace |
-| Multiple halo instances reply to the same message | Only one process should hold the Socket Mode connection. Check `~/.halo/global/server.pid` for the lock |
+| Multiple halo instances reply to the same message | Only one process should hold the Socket Mode connection. Check `~/.halo/global/server.lock` for the lock |
 
 ## Multi-workspace setup
 

package/bundled-docs/guide/channels/telegram.md

@@ -24,27 +24,25 @@ Sending `/setcommands` to BotFather lets Telegram clients show a menu next to th
 /setcommands → pick your bot → paste:
 
 start - 开始 / start
-new - 新会话 / new session
-list - 会话列表 / list sessions
-switch - 切换会话 / switch session
-stop - 中断任务 / stop running task
-compact - 压缩上下文 / compact context
-ws - 查看/切换 workspace
+session - 会话管理 / manage sessions
+agent - 智能体 / manage agents
+skill - 技能 / manage skills
+workspace - 查看/切换 workspace
 help - 帮助 / help
 ```
 
 ## Step 3 — Add the account in halo admin
 
-Open halo admin → **Channels** → **Telegram** → **Add Account**:
+Open halo admin → **Channels** → **Telegram** → **Add Bot**:
 
 | Field | Value |
 |---|---|
-| Bot token | the `…:ABC…` from Step 1 |
-| Workspace path | absolute path, e.g. `/home/ubuntu/my-project` |
-| Label | optional |
+| Bot Token (from @BotFather) | the `…:ABC…` from Step 1 |
+| Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | a label for the account |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` |
-| Allowed users | optional whitelist; comma-separated user IDs and/or `@usernames`. Empty = anyone can talk to the bot |
+| Allowed users (optional) | whitelist; comma-separated user IDs and/or `@usernames`. Empty = anyone can talk to the bot |
 
 On submit halo calls Telegram's `getMe` to validate the token and auto-fill `botUsername`. If that call fails the account isn't created.
 
@@ -52,7 +50,7 @@ On submit halo calls Telegram's `getMe` to validate the token and auto-fill `bot
 
 - **Empty** — anyone who finds the bot can chat with it. Fine for personal bots, dangerous if the bot is `full`-access
 - **Numeric IDs** (e.g. `123456789`) — recommended. A user's id is stable and you can find it by sending `/start` to `@userinfobot` in Telegram
-- **`@username`** — works for inbound filtering but **cron fan-out skips them** (Telegram's Bot API needs a numeric chat id, and `@username` lookup isn't always reliable)
+- **`@username`** — works for inbound filtering (matched case-insensitively against the sender's current username, so it breaks if they rename)
 
 For team bots prefer numeric IDs.
 
@@ -60,13 +58,15 @@ For team bots prefer numeric IDs.
 
 In Telegram, search the bot's username (`@halo_dev_bot`) → press **Start** → say `hello` → expect a streamed reply.
 
-If nothing happens, check halo server logs for `[telegram]` lines.
+If nothing happens, check halo server logs for `[Telegram]` lines.
 
 ## How halo handles inbound
 
 - **Private chats** — every message routes to the bot
-- **Group chats** — not supported in v1 (group messages are dropped)
-- **Photos / documents** — the file URL is included in the agent's input text; images aren't yet sent to vision automatically (by design — Telegram's photo URLs are short-lived and the upstream LLM can't always reach them)
+- **Group chats** — supported. Each member talks to their **own** session (the same one they use in DM with the bot), and the bot replies in the group. `allowedUsers` is checked against the sender, so non-whitelisted members are refused there too. By default Telegram's *privacy mode* only delivers `/command@yourbot` and replies to the bot's messages; to have the bot see every group message, send `/setprivacy` → **Disable** to BotFather (then re-add the bot to the group) or make it a group admin
+- **Photos** — downloaded, sent to the model as vision input and saved under `<workspace>/.halo/assets/telegram/inbound/<accountId>/<date>/`; the saved path is appended to the message text
+- **Documents / voice / round video** — downloaded (20 MB cap) to the same folder; the agent gets the saved path in the message text, not the content
+- **After a server restart** — if the agent was mid-task when halo restarted, its reply still reaches the most recent private chat the user talked in; a group conversation reconnects on the user's next message there
 - **Slash commands** — handled by halo, not by Telegram. The BotFather menu in Step 2 is just a UI hint
 
 ## Slash commands
@@ -74,31 +74,25 @@ If nothing happens, check halo server logs for `[telegram]` lines.
 | Command | Effect |
 |---|---|
 | `/start` | Welcome message |
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting Telegram
 
-When a cron job is created from inside a Telegram chat, the dispatcher targets that chat. From the admin UI you can also enter chat IDs directly (comma-separated for fan-out). The dispatcher resolves recipients in this order:
-
-1. Explicit chat IDs on the cron target row (if provided in the form)
-2. Fan-out to every numeric ID in the account's `allowedUsers` whitelist
-3. The most-recent inbound chat ID, as a single-recipient fallback
-
-Want to fan out a daily report to your whole team? Add their numeric IDs to `allowedUsers` and create a cron without an explicit chat ID — halo delivers to each one and records per-recipient ✓/✗ in the cron run history.
+When a cron job is created from inside a Telegram chat, the dispatcher targets that chat. From the admin UI you can also enter chat IDs directly (comma-separated for fan-out). A Telegram target **must** carry an explicit numeric chat ID (for a private chat it equals the user ID; a group's is negative) — there is no fallback to the whitelist or to the last inbound chat, and the dispatch fails without one. Per-recipient ✓/✗ is recorded in the cron run history. A report longer than 4000 characters is sent as several messages, in order.
 
 ## Common problems
 
 | Symptom | Cause / fix |
 |---|---|
-| "Unauthorized" / `getMe` fails on Add Account | Bot token has a typo, or the bot was deleted in BotFather |
+| "Unauthorized" / `getMe` fails on Add Bot | Bot token has a typo, or the bot was deleted in BotFather |
 | Bot exists but doesn't reply | Check `allowedUsers` — if non-empty, your user must be in it |
-| Bot used to work, now silent | Maybe two halo processes are running and stealing each other's `getUpdates` long-poll. Check `~/.halo/global/server.pid` |
-| Group messages don't trigger the bot | Expected — groups aren't supported in v1 |
-| Cron fan-out skips a whitelisted user | The user is listed as `@username`. Add their numeric ID instead |
+| Bot used to work, now silent | Maybe two halo processes are running and stealing each other's `getUpdates` long-poll. Check `~/.halo/global/server.lock` |
+| Group messages don't trigger the bot | Privacy mode is on (the default): only `/command@yourbot` and replies to the bot get through. Disable it with BotFather `/setprivacy` and re-add the bot, or make it a group admin |
 
 ## Multi-bot setup
 

package/bundled-docs/guide/channels/web.md

@@ -13,13 +13,13 @@ The token is **the** credential — anyone holding it can talk to the agent at t
 
 ## Step 1 — Create an account
 
-Open halo admin → **Channels** → **Web** → **Add Account**:
+Open halo admin → **Channels** → **Web** → **Create Access**:
 
 | Field | Value |
 |---|---|
-| Workspace path | absolute path, e.g. `/home/ubuntu/my-project` |
-| Label | optional |
-| Access level | `readonly` (default), `workspace`, or `full` |
+| Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | a label for the account |
+| Access level | `readonly` (default), `workspace`, `full`, or `observer` (global read-only, for dashboards / metrics) |
 | Language | `en` or `zh` |
 
 Click **Create**. The success screen shows the auto-generated token **once** — copy it now, you can't retrieve it again. (You can always delete the account and create a new one if you lose the token.)
@@ -55,18 +55,20 @@ Parse the `type` field on each event to render text vs tool calls vs completion.
 | Method | Path | Purpose |
 |---|---|---|
 | `POST /api/web/chat` | Send a message; SSE response |
+| `POST /api/web/sessions` | Mint a new root session in the token's namespace; returns `{sessionId}` |
 | `POST /api/web/stop` | Cancel the running task |
 | `GET /api/web/history` | Fetch session message history |
 | `GET /api/web/subscribe` | Reconnect to a running session's SSE stream |
+| `GET /api/web/file?path=…` | Fetch a file from the bound workspace (path relative to it; `.halo` runtime state is refused) |
 
-All four accept the same auth header.
+All six accept the same auth header.
 
 ### Per-request overrides
 
 By default each token is locked to the workspace and active session set by the admin. External integrations (notably the [ACP adapter](acp.md)) need finer control:
 
 - `workspace` — server-side absolute path, **gated on `accessLevel === 'full'`** (readonly / workspace tokens can't escape their bound workspace; the override is rejected)
-- `sessionId` — explicit halo session id; lets clients pre-mint stable ids and address them across reconnects
+- `sessionId` — explicit halo session id; lets clients address a session across reconnects. **Gated on ownership**: `full` tokens may name any id; `readonly` / `workspace` tokens only ids under their own account (`web_<accountId>_*`, e.g. minted by `POST /api/web/sessions`) — anything else is `403`
 - `agentId` — only used when the request creates a new session
 
 These can be passed as POST body fields, headers (`x-workspace`, `x-session-id`, `x-agent-id`), or query params (`?workspace=…&sessionId=…&agentId=…`). POST body wins on conflict.
@@ -86,7 +88,7 @@ For browser apps you almost never want these — leave them off and use the per-
 }
 ```
 
-Images go to the LLM as multimodal content. Audio and other binary uploads aren't supported on this endpoint directly — for those, save the file to `<workspace>/.halo/assets/web/inbound/<accountId>/<date>/` first (out-of-band) and reference its path in your message text.
+Images go to the LLM as multimodal content. Any other `mimeType` (audio, PDF, …) in the same array is not sent to the model: the server saves it to `<workspace>/.halo/assets/web/inbound/<accountId>/<date>/` and appends a `[语音已保存: <path>]` line to your message so the agent can open it with its file tools.
 
 The standalone web-demo handles voice + arbitrary files for you; if you want that, use it as a reference implementation.
 
@@ -96,10 +98,11 @@ Slash commands are intercepted before they reach the agent — same set as every
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 Send a slash command exactly like a normal message — the server detects the leading `/`.
@@ -109,7 +112,8 @@ Send a slash command exactly like a normal message — the server detects the le
 | Symptom | Cause / fix |
 |---|---|
 | `401` on every call | Missing `x-token` header, or token is for a deleted account |
-| `403` when passing `workspace=…` | Token is `readonly` / `workspace` access — only `full` can override |
+| `429` | 5 bad tokens from one IP within 15 minutes locks that IP out for 15 minutes (in-memory, cleared on restart) |
+| `403` when passing `workspace=…` or a foreign `sessionId` | Token is `readonly` / `workspace` access — only `full` can override the workspace or address sessions it didn't mint |
 | SSE stream hangs forever | Reverse proxy buffering. Disable buffering for `text/event-stream` (nginx: `proxy_buffering off`, Cloudflare: enable streaming) |
 | Token leaked accidentally | Delete the account in admin, create a new one. The old token is invalidated immediately |
 | Want to share one token across multiple users | Don't — every request would land on the same active session. Create one account per user / app |
@@ -139,9 +143,9 @@ Alternatively, the gear icon (header / login screen) opens **direct-connect mode
 ## Security notes
 
 - **Tokens are unhashed** in `~/.halo/secrets/channels/channels.db`. Restrict that file to the user that runs halo
-- **No rate limit at the channel level** — if you expose the API on the public internet, put a reverse proxy with rate limits in front
+- **Bad-token lockout only** — 5 invalid tokens from one IP in 15 minutes locks that IP out (`429`) for 15 minutes; there is no per-token request rate limit, so if you expose the API on the public internet put a reverse proxy with rate limits in front
 - **Admin endpoints** (`POST /api/web/accounts`, `PATCH`, `DELETE`) require admin cookie auth, **not** the token. They're for the admin panel, not for the token holder
-- A `full`-access token can call `/workspace <abs-path>` to switch the bound workspace database-side. If you don't want that, give out `workspace` or `readonly` tokens instead
+- A `full`-access token can call `/workspace switch <abs-path>` to switch the bound workspace database-side. If you don't want that, give out `workspace` or `readonly` tokens instead
 
 ## Reference
 

package/bundled-docs/guide/channels/wechat.md

@@ -21,18 +21,18 @@ Halo auto-creates `.halo/` inside the folder if it doesn't exist; the path itsel
 
 ## Step 2 — Open the admin scan flow
 
-Open halo admin → **Channels** → **WeChat** → **Add Account**.
+Open halo admin → **Channels** → **WeChat** → **Add Bot**.
 
 The form is **just the workspace + label + access level + language** — no bot token field, because the token comes from the scan:
 
 | Field | Value |
 |---|---|
-| Workspace path | absolute path from Step 1, e.g. `/home/ubuntu/my-project` |
-| Label | optional, shown in admin's account list |
+| Bind to workspace | absolute path from Step 1, e.g. `/home/ubuntu/my-project` |
+| Name (optional) | shown in admin's account list |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` |
 
-Click **Generate QR**. Halo hits `ilinkai.weixin.qq.com` to mint a fresh QR code and starts a poll loop waiting for the scan.
+Click **Next: Scan**. Halo hits `ilinkai.weixin.qq.com` to mint a fresh QR code and starts a poll loop waiting for the scan.
 
 > **What the access level covers.** A WeChat account is bound to exactly one WeChat user — the one who scans — so there's no whitelist to configure; the scanner *is* the whitelist. The level you choose here is what that phone gets: `full` means whoever holds the unlocked phone has shell access as the server user. The same applies to invite QRs minted with `/qr full` from inside the chat — each scan creates a separate account at the level you named, so hand those out as you would an SSH key.
 
@@ -43,19 +43,19 @@ Click **Generate QR**. Halo hits `ilinkai.weixin.qq.com` to mint a fresh QR code
 3. Aim at the QR shown in the admin UI
 4. Tap **Confirm Login / 确认登录** on the phone
 
-Within a few seconds the admin UI shows "登录成功" / "Logged in" and switches to the success page. Behind the scenes:
+Within a few seconds the admin UI shows "Connected (<id>)" and closes the dialog. Behind the scenes:
 
 - iLink returns the bot's token, the IDC-specific `baseUrl`, and your WeChat-side `ilink_user_id`
 - Halo writes those into the new account row
 - The long-poll loop starts immediately — the bot is now live
 
-The QR is valid for ~3 minutes; if it expires the admin UI auto-refreshes. If you cancel and come back later, just open the form again — a new QR is minted.
+The server waits up to ~8 minutes for the scan and gives up after the QR has expired three times; the dialog then shows the error and a **Start over** button. If you cancel and come back later, just open the form again — a new QR is minted.
 
 ## Step 4 — Test it
 
 The bot's name in your WeChat contacts is whatever the iLink platform set it to (typically a generic placeholder like `小助手`; you can rename it locally). Open the bot's chat in WeChat and send `hello` → expect a streamed reply.
 
-If nothing happens, check halo server logs for `[wechat]` lines.
+If nothing happens, check halo server logs for `[WeChat]` lines.
 
 ## How halo handles inbound
 
@@ -63,7 +63,8 @@ If nothing happens, check halo server logs for `[wechat]` lines.
 - **Images** — passed to the LLM as multimodal content
 - **Voice** — decrypted, saved under `<workspace>/.halo/assets/weixin/inbound/<accountId>/<date>/` (the `weixin` directory name is kept for backward compatibility with existing workspaces), path included in the agent's input
 - **Video / files** — same as voice
-- **Group chats** — not supported in v1 (group messages are dropped)
+- **Group chats** — not supported: the WeChat (iLink) bot is a one-to-one contact and the platform doesn't deliver group messages to it, so there is nothing for halo to handle
+- **After a server restart** — if the agent was mid-task when halo restarted, its reply still reaches each user who has chatted with the bot (as long as the stored `context_token` is still accepted; otherwise it fails with `ret=-2` until they write again)
 - **Self-loop** — bot-authored messages are filtered out
 
 ## Slash commands
@@ -72,12 +73,13 @@ Same set as the other channels — type as plain text in your WeChat DM with the
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
-| `/qr [level]` | Generate an invite QR (admin only) |
+| `/qr [level]` | Generate an invite QR (`full`-access bot only; `level` = `readonly` (default) / `workspace` / `full`) |
 
 ## Cron jobs targeting WeChat
 
@@ -94,11 +96,10 @@ Fan-out across multiple WeChat users is not supported — one bot, one owner.
 | Symptom | Cause / fix |
 |---|---|
 | QR shows but scan does nothing | iLink platform thinks the QR is for a different account. Cancel and regenerate |
-| "二维码已过期" / QR expired | Admin UI should auto-refresh. If not, click Generate again |
+| "登录超时：二维码多次过期" / QR expired | Click **Start over** in the dialog and scan the new QR |
 | Bot stops responding after a few hours | Long-poll likely lost its `syncBuf`. Restart the server; reconnect is automatic |
-| Two halo processes both poll the same bot | Each process gets a copy of every message, replied twice. Make sure only one server runs — see `~/.halo/global/server.pid` |
-| Group chat doesn't trigger the bot | Expected — groups aren't supported in v1 |
-| Sent voice message returns no reply | Check that the account has `workspace` or `full` access; readonly cannot save inbound media |
+| Two halo processes both poll the same bot | Each process gets a copy of every message, replied twice. Make sure only one server runs — see `~/.halo/global/server.lock` |
+| Group chat doesn't trigger the bot | Expected — WeChat (iLink) doesn't support group chats for bots; talk to it one-to-one |
 | Cron push or a delayed reply fails with `ret=-2 prepare failed` while fresh chat replies work | Three causes: the report exceeds 16 KB (halo chunks at 3500 chars, so this is rare now); the account has no stored `context_token` for the recipient yet — the gateway wants outbound to echo the user's latest inbound token, which halo persists on every inbound message since 1.1.8; or that token has **expired** — the gateway stops accepting it some time after the user's last message (the window isn't fixed; failures were seen 12 min and 79 min after the last inbound), and only a new inbound message from that user refreshes it. In all cases: send the bot any message once and the next push carries a fresh token. The error names which case it is (`context_token missing` / `context_token age 79m`), and a dropped chat reply now shows up as a `⚠️ WeChat delivery failed` notification in the session log (admin Sessions tab) instead of vanishing silently |
 
 ## Multi-workspace / multi-bot

package/bundled-docs/guide/channels/wecom.md

@@ -40,7 +40,7 @@ Open halo admin → **Channels** → **WeCom** → **Add Bot**:
 | Bot ID | from Step 3 |
 | Secret | from Step 3 |
 | Bind to workspace | absolute path, e.g. `/home/ubuntu/my-project` |
-| Name | optional label |
+| Name (optional) | a label for the account |
 | Access level | `readonly` (default), `workspace`, or `full` |
 | Language | `en` or `zh` — for hints and command replies |
 
@@ -91,16 +91,21 @@ When the agent emits a `MEDIA:<path>` line (a file under the workspace), halo up
 
 Replies render **Markdown natively** — headings, bold, lists, quotes, links, code blocks and tables all display as formatted text.
 
+### After a server restart
+
+If the agent was mid-task when halo restarted, its reply still reaches the **most recent** chat the bot talked in (one per bot). Because the original message can no longer be answered directly, that reply arrives as a regular pushed message rather than as a reply to your message; once you write again, replies go back to normal.
+
 ## Slash commands
 
 Same set as the other channels — type as plain text in a **single chat** (commands are ignored in groups, where the shared session belongs to everyone):
 
 | Command | Effect |
 |---|---|
-| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` |
+| `/session <verb>` | Session lifecycle: `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` |
 | `/agent <verb>` | Manage agents (`list` / `switch` / `desc` open to all; `delete` full; `create` / `update` via skill, full) |
 | `/skill <verb>` | Manage skills (`list` / `desc` open; `disable` / `enable` workspace; `delete` full; `create` / `update` via skill, full) |
 | `/workspace <verb>` | Workspace: `info` (all) / `switch <path>` (full) / `setup` / `tidy` (workspace) / `share` (full) |
+| `/cron` `/acp` `/extension` | Skill-backed object commands (full access); `/evo [hint]` queues a self-evolution run |
 | `/help` | List commands — object commands show only the verbs you can run |
 
 ## Cron jobs targeting WeCom

package/bundled-docs/guide/chat.md

@@ -28,16 +28,16 @@ A change applies from the next message you send, and the level is saved per sess
 
 ## Context injection
 
-Next to the chat is a `📎 Context` toggle (on by default). When on, Halo auto-injects:
+The input toolbar shows a context chip (the open file's name, or the selection) — click it to toggle; on by default. When on, Halo auto-injects:
 - The currently open file path: `[Currently viewing: src/foo.ts]`
 - The editor's current selection: `[Selected text in foo.ts:10-25]\n\`\`\`...\n\`\`\``
 
-Turn it off if you don't want that context injected.
+Click the chip (it turns struck-through) if you don't want that context injected.
 
 ## `@` file mention
 
 Typing `@` in the input opens a file search:
-- Real-time fuzzy matching (150 ms debounce)
+- Real-time fuzzy matching (120 ms debounce)
 - Selecting inserts a path chip
 - You can `@` multiple files back-to-back
 
@@ -49,7 +49,7 @@ The search scans the whole project on the server — independent of Explorer exp
 - **Paste**: paste an image from the clipboard
 - **Button**: click the 📎 on the left
 
-Images are sent to the agent as base64, with multimodal support (Claude 4.6 can see images).
+Chat attachments are images only — other dropped or pasted files are ignored. Images are sent to the agent as base64, with multimodal support (Claude 4.6 can see images).
 
 ## Slash commands
 
@@ -59,13 +59,14 @@ Most commands are noun-verb **object commands**: `/<obj> <verb> [args]`. Bare `/
 
 | Command | Purpose |
 |---|---|
-| `/session <verb>` | Manage sessions — `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context`. All built-in, available to everyone. `new` starts a fresh conversation (old session stays in the sidebar; running sub-agents keep going); `compact` keeps the most recent N messages intact (N defaults to 5, `general.compact.keep_messages`); `context` shows token usage, agent info, and available tools |
+| `/session <verb>` | Manage sessions — `new` / `list` / `switch <n>` / `stop` / `interrupt` / `compact` / `context` / `info` (session tree). All built-in, available to everyone. `new` starts a fresh conversation (old session stays in the sidebar; running sub-agents keep going); `compact` keeps the most recent N messages intact (N defaults to 5, `general.compact.keep_messages`); `context` shows token usage, agent info, and available tools |
 | `/clear` | Admin-UI alias for `/session new` |
 | `/agent <verb>` | Manage agents — `list` / `switch <name\|index>` / `desc` (built-in, open to all) · `delete` (built-in, full access) · `create` / `update` (handled by the `agent` skill, full access) |
 | `/skill <verb>` | Manage skills — `list` / `desc` (built-in, open to all) · `disable` / `enable` (built-in, workspace access) · `delete` (built-in, full access) · `create` / `update` (handled by the `skill` skill, full access) |
 | `/workspace <verb>` | Manage the workspace — `info` (built-in, open to all) · `switch <path>` (built-in, full access) · `setup` / `tidy` (workspace skill, workspace access; init / reorganize `.halo/` INDEX.md / INSTRUCTIONS.md / memory/) · `share` (workspace skill, full access; export a shareable bundle) |
 | `/cron <verb>` | Scheduled agent runs — `create` / `list` / `update` / `enable` / `disable` / `delete` (cron skill, full access) |
 | `/acp <verb>` | Talk to other agents over ACP — `kiro <q>` / `claude <q>` ask a local agent directly; `add` / `list` / `remove` manage generated `ask-<label>` bindings (acp skill, full access) |
+| `/extension <verb>` | Canvas preview extensions — `install <id\|zip\|url>` / `list` / `remove <id>` (extension skill, full access) |
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/help` | List every command — object commands only show the verbs you can run |
 
@@ -103,8 +104,8 @@ Three ways to cut in while the agent is running:
 The ring in the bottom-right of the input shows context window usage:
 - Green: < 50%
 - Yellow: 50–70%
-- Orange: 70–90%
-- Red: > 90%
+- Orange: 70–85%
+- Red: > 85%
 
 Reaching `compressAt` (default 90%, setting `general.compact.compress_at`) auto-triggers compact. If the LLM summary fails or times out, Halo falls back to a local compact (notice: `Auto-compacted N older messages (local fallback — LLM summary failed: <reason>)`) rather than retrying. An auto-compact has no overall time limit — it only times out after 10 minutes with no data from the model. While the agent is running you can't click the TokenRing (guarded by `isStreaming`).
 
@@ -114,7 +115,7 @@ Your sessions are listed as vertical tabs on the right edge of the chat panel:
 - Lists the workspace's main sessions, newest first; scroll down to load older ones
 - Click a tab to show that session. The one you left keeps running and streaming in its own tab. Each tab's dot shows its state: pulsing amber while it works, blue when new output arrived in the background, green otherwise (including sessions not opened since the page loaded)
 - **+** (or `/session new`) opens a fresh tab; the session is created when you send its first message
-- Hover a tab to rename it (pencil); ✕ deletes it after a confirmation — deletion can't be undone
+- Hover a tab to rename it (pencil) or delete it (trash icon, after a confirmation) — deletion can't be undone
 - Drag the list's left edge to make it wider or narrower, or collapse it to a thin strip of initials
 - After a refresh, the session you were on reopens
 
@@ -126,6 +127,6 @@ Long messages you sent are collapsed to a one-line header: a chevron, the send t
 
 **"Queued" hint**: the previous turn hasn't finished; your message is queued and will run next turn.
 
-**"Rate limited, retrying in Xs..."**: Bedrock throttled; automatic exponential backoff (up to 5 retries).
+**"Rate limited, retrying in Xs..."**: the model provider throttled; automatic backoff, up to `general.agent.max_retries` attempts (default 5).
 
 **A sudden `[Message from xxx]`**: a sub-agent finished and auto-reported back to the parent agent's conversation.

package/bundled-docs/guide/cli.md

@@ -29,7 +29,7 @@ bundle flattens them.
 # 2. build the upstream artifacts the bundle consumes
 pnpm --filter @turmind/halo-core build
 pnpm --filter @turmind/halo-server build
-cd packages/admin && npx next build --no-lint && node scripts/copy-monaco.mjs && cd ../..
+pnpm --filter @turmind/halo-admin build
 # 3. stage the release bundle — HALO_RELEASE=1 stamps the bare version
 #    (0.1.2), NOT the default <version>-<sha>: a `-<sha>` suffix is a semver
 #    prerelease that `npm install` skips and never tags as `latest`.
@@ -136,6 +136,7 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | `/session interrupt` | Interrupt the running turn now (aborts a command mid-run); any messages queued while busy then run as one follow-up turn |
 | `/session compact` | Compact session context |
 | `/session context` | Show context window + agent info |
+| `/session info` | Show the session tree (descendants) |
 | `/agent <verb>` | Manage agents: `list` / `switch <name\|index>` / `desc` / `delete` / `create` / `update` |
 | `/skill <verb>` | Manage skills: `list` / `desc` / `disable` / `enable` / `delete` / `create` / `update` |
 | `/workspace info` | Show current workspace |
@@ -143,6 +144,7 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | `/workspace setup` / `/workspace tidy` / `/workspace share` | Set up / tidy the `.halo/` knowledge files, or export a shareable bundle (workspace skill) |
 | `/cron <verb>` | Manage scheduled agent runs: `create` / `list` / `update` / `enable` / `disable` / `delete` |
 | `/acp <verb>` | Ask other agents over ACP (`kiro <q>` / `claude <q>`) and manage `ask-*` bindings (`add` / `list` / `remove`) |
+| `/extension <verb>` | Canvas preview extensions: `install` / `list` / `remove` (full access only) |
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/quit` | Exit |
 
@@ -216,7 +218,7 @@ same binary. `start -d` runs it in the background **with a bounded respawn
 supervisor**: the detached process supervises the server and brings it back on
 a crash (non-zero exit, or a kill by anything other than SIGTERM/SIGINT), at
 most 5 times per 5 minutes with a 2s pause, logging each decision as
-`[respawn] …` into `~/.halo/global/logs/server.log`. `halo server stop` is
+`[respawn] …` into `~/.halo/logs/server.log`. `halo server stop` is
 recognized as intentional and never respawns; `halo server stop|restart|status`
 still target the server's own pid. Full policy in
 [dev/deploy.md](../dev/deploy.md#crash-semantics--why-restarton-failure-is-load-bearing).
@@ -226,8 +228,9 @@ still target the server's own pid. Full policy in
 ```
 packages/cli/
   src/
-    index.ts        — Entry: subcommand dispatch (tui/cli/agents/sessions/server/setup/acp), SIGINT/SIGTERM handling
+    index.ts        — Entry: subcommand dispatch (tui/cli/agents/sessions/server/setup/upgrade/acp), SIGINT/SIGTERM handling
     harness.ts      — Shared agent harness wrapping SessionManager
+    server-supervisor.ts — Respawn policy for `halo server start -d`
     cli.ts          — Non-interactive: stdin/args → agent → stdout → exit
     tui.tsx         — Interactive entry: mounts the ink app
     tui/
@@ -247,9 +250,8 @@ Session prefix: `cli_`. Sessions are persisted to `<workspace>/.halo/sessions/`
 
 ### Initialization
 
-The CLI replicates the server's init sequence:
+`tui` / `cli` / `agents` / `sessions` refuse to run ("~/.halo/global/ not initialized. Run halo setup first.") until `halo setup` has seeded `~/.halo/global/`. Then the CLI replicates the server's init sequence (`initRuntime()` in `harness.ts`):
 1. `initLogger()` — redirect console to stderr + file logger
-2. `ensureHaloHome()` — ensure `~/.halo/` structure
-3. `initBwrapCheck()` — probe sandbox availability
-4. `setSandboxHiddenPaths()` — configure sandbox paths
-5. `new SessionManager(workspace)` — create agent session manager
+2. `initBwrapCheck()` — probe sandbox availability
+3. `setSandboxHiddenPaths()` — configure sandbox paths
+4. `new SessionManager(workspace)` — create agent session manager (the workspace's `.halo/` is seeded via `ensureWorkspaceHalo`)