@turmind/halo 2.2.2 → 2.2.4

package/bundled-docs/guide/cli.md

@@ -84,7 +84,7 @@ To list agents or sessions without running a prompt, use the dedicated subcomman
   ```
   [ 17:23:02  in 0.0K  out 0.1K  ctx 5.8K  read 5.3K  write 0.3K  cache 94%  e2e 3.3s  think medium  claude-sonnet-4-6 ]
   ```
-- **json format**: Single JSON object on stdout after completion (`text` has the same final-answer semantics as text format; `notices` holds the same root system notices as an array of strings, without the `ℹ️ ` prefix):
+- **json format**: Single JSON object on stdout after completion (`text` has the same final-answer semantics as text format; `notices` holds the same root system notices as an array of strings, without the `ℹ️ ` prefix; `error` is `null` on success, else the reason — an error event's text, or the root's last-turn error such as a model refusal):
 
 ```json
 {
@@ -106,10 +106,12 @@ halo cli -w /path/to/review-ws "review the diff" --format json | jq '.text'
 # Pipe content in
 git diff HEAD~1 | halo cli -w /path/to/review-ws "review this diff"
 
-# Exit code: 0 = success, 1 = error, 130 = SIGINT, 143 = SIGTERM (graceful: session repaired + flushed before exit)
+# Exit code: 0 = success, 1 = error (including a model refusal on the root's last turn — Anthropic's refusal or an OpenAI-format provider's content-filter block), 130 = SIGINT, 143 = SIGTERM (graceful: session repaired + flushed before exit)
 halo cli "check for issues" && echo "OK" || echo "FAILED"
 ```
 
+A refusal on a sub-agent's turn does not change the exit code — it reaches the root as an aborted report, and the run exits 0 if the root then wraps up normally. A later root turn that ends normally clears an earlier refusal.
+
 When stdin is not a TTY, piped input is appended after the positional prompt. With a positional prompt, stdin is only read if its first data arrives within 0.5 s — then to EOF, however long it takes. Otherwise it's ignored, so an open-but-idle stdin (scripts, CI, cron, `ssh host 'halo cli …'` without `-t`) no longer hangs the run. A producer that takes longer than that to print anything gets ignored too; capture it first (`out=$(slow-cmd); halo cli "summarize" <<<"$out"`). Without a positional prompt, stdin *is* the prompt: `halo cli` waits for EOF, and after 1 s of silence prints one `waiting for the prompt on stdin` hint to stderr.
 
 ## TUI Mode (interactive)
@@ -308,35 +310,6 @@ the caller-side `auth: sigv4` remote, session dirs and ops notes:
 [design/agentcore.md](../design/agentcore.md). The hub skill `agentcore-deploy`
 builds the image and creates the runtime for you.
 
-## Linked machine (`halo node`)
-
-```bash
-HALO_NODE_TOKEN=<token> halo node --server https://halo.example.com --root ~/proj [--allow-shell]
-```
-
-Links this machine to a workspace on a halo server, so that workspace's
-full-access agents can work on files here with the `node_*` tools. Runs in the
-foreground, reconnects on its own, Ctrl-C to stop. Needs no `halo setup` and
-no model keys — nothing is written under `~/.halo/`. Create the token in
-Admin → Channels → Linked machines.
-
-On Linux (x86_64 / arm64 / armv7) the standalone `halo-node` binary from the
-GitHub release does the same job with the same flags and doesn't need Node.js
-(`curl -fsSL …/install.sh | sh` installs it); `halo node` there prints a
-one-line `[Node] tip:` with that command. See
-[node.md](node.md#2-run-it-on-the-machine).
-
-| Flag / env | Meaning |
-|---|---|
-| `--server <url>` | Server address, `http(s)://host:port` (`ws(s)://` also accepted) — required |
-| `--token <t>` / `HALO_NODE_TOKEN` | Pairing token — required; prefer the env var (flags show up in `ps`) |
-| `--root <dir>` | Folder to share; every path must stay inside it. Omit (or `/`) for whole-machine mode: any path this user can reach, relative paths from the current dir |
-| `--allow-shell` | Let agents run commands (`node_run`) as this user, not sandboxed. Off by default |
-| `--header "Name: value"` | Repeatable. Extra header on the connection, for an auth proxy in front of the server |
-
-Exits 1 on a rejected / revoked token, a deleted workspace or a protocol
-mismatch; retries everything else. Full guide: [node.md](node.md).
-
 ## Architecture
 
 ```

package/bundled-docs/guide/node.md

@@ -1,6 +1,6 @@
-# Linked machines (`halo node`)
+# Linked machines (`halo-node`)
 
-Let a workspace's agents work on files on **your own computer** — a laptop, a desktop, a box behind NAT — while the agents themselves keep running on the halo server. You run `halo node` on that machine; it dials out to the server (no port to open), and the workspace's agents get `node_*` tools that read, write, search and (if you allow it) run commands there.
+Let a workspace's agents work on files on **your own computer** — a laptop, a desktop, a box behind NAT — while the agents themselves keep running on the halo server. You run `halo-node` on that machine; it dials out to the server (no port to open), and the workspace's agents get `node_*` tools that read, write, search and (if you allow it) run commands there.
 
 ```
 [your laptop]                               [server]
@@ -8,24 +8,21 @@ halo-node --root ~/proj ──WebSocket──────▶ halo server ──
   (files, optional shell)                     node_read / node_write / … / node_run
 ```
 
-Two clients do the same job, with the same flags and the same behaviour:
+The machine runs `halo-node`, a single binary attached to every GitHub release for **Linux (x86_64 / arm64 / armv7)**, **macOS (Apple silicon / Intel)** and **Windows (amd64)**. It needs no Node.js, no `halo setup` and no model keys, and writes nothing under `~/.halo/`. The Linux build is ~7 MB and idles at about 9 MB of memory.
 
-- **Linux (x86_64 / arm64 / armv7) and Windows (amd64)**: `halo-node`, a single binary attached to every GitHub release. It needs no Node.js. The Linux build is ~7 MB and idles at about 9 MB of memory.
-- **macOS** (or a Linux / Windows machine that already has the npm package): `halo node` from `npm install -g @turmind/halo`.
+Supported: Linux and Windows run vet and the tests in CI (Linux arm64 / armv7 under qemu). The macOS builds are only cross-compiled — not tested on a Mac; on macOS, file errors from the agent's tools can read `Unknown system error -<n>` instead of the usual `ENOENT: no such file or directory` text. Windows `node_run` commands go to `cmd.exe`, with UTF-8 output and a GBK fallback.
 
-Neither needs `halo setup` or model keys, and neither writes anything under `~/.halo/`.
-
-Supported: **Linux, macOS and Windows amd64**. The Go client is tested natively on Linux and Windows CI; macOS uses npm. Windows `node_run` commands go to `cmd.exe`, with UTF-8 output and a GBK fallback.
+> `halo node` (the npm client from `npm install -g @turmind/halo`) was removed in 2.2.4; use `halo-node`. Same flags, same token.
 
 ## 1. Create a token
 
-Admin → **Channels → Linked machines** → **Add machine**. Pick the workspace and a machine name (`a-z 0-9 -`, e.g. `mbp`; unique within the workspace — the agent uses it to address the machine). The dialog shows two commands to copy: one installs `halo-node` on Linux and runs it with `~/.local/bin` prepended to `PATH` (where a non-root install lands), the other runs the npm `halo node` client. On Windows, use the standalone exe below instead. The install link points at the server's own release, so the machine and the server come from the same version.
+Admin → **Channels → Linked machines** → **Add machine**. Pick the workspace and a machine name (`a-z 0-9 -`, e.g. `mbp`; unique within the workspace — the agent uses it to address the machine). The dialog shows two commands to copy: **Linux / macOS** installs `halo-node` with the install script and runs it with `~/.local/bin` prepended to `PATH` (where a non-root install lands); **Windows** downloads `halo-node-windows-amd64.exe` in PowerShell and runs it. The download link points at the server's own release, so the machine and the server come from the same version.
 
 The token stays on the list row (copy button). Deleting the row revokes it at once and disconnects the machine.
 
 ## 2. Run it on the machine
 
-**Linux** — install once with the release's install script, then run:
+**Linux / macOS** — install once with the release's install script, then run:
 
 ```bash
 curl -fsSL https://github.com/turmind/halo-agent/releases/latest/download/install.sh | sh
@@ -36,7 +33,7 @@ halo-node --server https://halo.example.com --root ~/proj
 
 What the script does (`sh`, busybox included; curl or wget):
 
-- picks `halo-node-linux-{amd64,arm64,armv7}` from `uname -m` (`armv8l`, a 64-bit kernel with 32-bit userland, gets armv7). Any other architecture, or not Linux, stops with a message.
+- picks the binary from `uname -s` and `uname -m`: on Linux `halo-node-linux-{amd64,arm64,armv7}` (`armv8l`, a 64-bit kernel with 32-bit userland, gets armv7); on macOS (`Darwin`) `halo-node-darwin-arm64` for `arm64` (Apple silicon) and `halo-node-darwin-amd64` for `x86_64` (Intel). Any other architecture or OS stops with a message.
 - downloads that release's binary and checks it against the release's `SHA256SUMS` (`sha256sum` or `shasum`). A mismatch stops with an error and leaves nothing behind. With neither tool installed it warns and skips the check.
 - installs to `/usr/local/bin/halo-node` when run as root, otherwise to `~/.local/bin/halo-node`. If that directory isn't in `PATH`, it says so. Debian, Ubuntu and Raspberry Pi OS add `~/.local/bin` to `PATH` only at a login after it exists, which is why the commands above (and the admin's) prepend it.
 - runs the downloaded binary's `--version` before replacing anything; a download that doesn't run stops with an error.
@@ -48,16 +45,19 @@ Each release's `install.sh` installs that release's binary. The admin's command
 **Manual download** — if you'd rather not pipe a script into `sh`, have only wget (`wget -qO- <url>/install.sh | sh` also works), or the machine can't reach GitHub (download on another machine, copy it over):
 
 ```bash
-A=$(uname -m); case "$A" in x86_64) A=amd64;; aarch64|arm64) A=arm64;; armv7l|armv8l) A=armv7;; *) echo "no halo-node build for $A — use npm" >&2;; esac
-curl -fLo halo-node "https://github.com/turmind/halo-agent/releases/latest/download/halo-node-linux-$A" && chmod +x halo-node
-# optional: verify
-curl -fsL https://github.com/turmind/halo-agent/releases/latest/download/SHA256SUMS | grep "halo-node-linux-$A\$" | sed "s/halo-node-linux-$A/halo-node/" | sha256sum -c
+O=$(uname -s | tr A-Z a-z)   # linux | darwin
+A=$(uname -m); case "$A" in x86_64) A=amd64;; aarch64|arm64) A=arm64;; armv7l|armv8l) A=armv7;; *) echo "no halo-node build for $A" >&2;; esac
+curl -fLo halo-node "https://github.com/turmind/halo-agent/releases/latest/download/halo-node-$O-$A" && chmod +x halo-node
+# optional: verify (macOS: shasum -a 256 -c instead of sha256sum -c)
+curl -fsL https://github.com/turmind/halo-agent/releases/latest/download/SHA256SUMS | grep "halo-node-$O-$A\$" | sed "s/halo-node-$O-$A/halo-node/" | sha256sum -c
 ./halo-node --server https://halo.example.com --root ~/proj
 ```
 
+On macOS, a binary downloaded in a browser is quarantined and Gatekeeper blocks it (the builds aren't notarized); clear that once before running it: `xattr -d com.apple.quarantine ./halo-node-darwin-*` (or whatever you renamed it to). `curl` / `wget` downloads — including `install.sh` — aren't quarantined.
+
 ### Windows (amd64)
 
-Download `halo-node-windows-amd64.exe` from the [GitHub release](https://github.com/turmind/halo-agent/releases/latest) matching your server (no npm or Node.js needed). Put it in e.g. `C:\halo-node`. In PowerShell:
+Download `halo-node-windows-amd64.exe` from the [GitHub release](https://github.com/turmind/halo-agent/releases/latest) matching your server (no Node.js needed; the admin's command does it with `Invoke-WebRequest` into the current folder). Put it in e.g. `C:\halo-node`. In PowerShell:
 
 ```powershell
 $env:HALO_NODE_TOKEN = '<token>'
@@ -66,30 +66,35 @@ $env:HALO_NODE_TOKEN = '<token>'
 
 The release's `SHA256SUMS` includes the exe; compare its entry with `Get-FileHash C:\halo-node\halo-node-windows-amd64.exe -Algorithm SHA256`. Use either `/` or `\` in paths; `~/` expands from `USERPROFILE`. Folder mode resolves symlinks and junctions before checking the root. Add `--allow-shell` only if you want commands as this Windows user. Stop the process before replacing the exe during an upgrade.
 
-**macOS (npm)**:
+It runs in the foreground and logs each call (`[Node] read src/app.ts`, `[Node] refused write ../x: outside root`). Ctrl-C stops it. It reconnects by itself after network drops or a server restart; it exits (code 1) on a bad / revoked token or when the workspace is gone.
 
-```bash
-npm install -g @turmind/halo                   # once
-export HALO_NODE_TOKEN=<token>
-halo node --server https://halo.example.com --root ~/proj
-```
+The admin row turns green (live, no refresh) and shows `folder · shell on/off · os`.
 
-On Linux, `halo node` still works, and prints one `[Node] tip:` line with the install command.
+### Flags
 
-Either one runs in the foreground and logs each call (`[Node] read src/app.ts`, `[Node] refused write ../x: outside root`). Ctrl-C stops it. It reconnects by itself after network drops or a server restart; it exits (code 1) on a bad / revoked token or when the workspace is gone.
+| Flag / env | Meaning |
+|---|---|
+| `--server <url>` | Server address, `http(s)://host:port` (`ws(s)://` also accepted) — required |
+| `--token <t>` / `HALO_NODE_TOKEN` | Pairing token — required; prefer the env var (flags show up in `ps`) |
+| `--root <dir>` | Folder to share; every path must stay inside it. Omit (or `/`) for whole-machine mode: any path this user can reach, relative paths from the current dir |
+| `--allow-shell` | Let agents run commands (`node_run`) as this user, not sandboxed. Off by default |
+| `--proxy <url>` | `http(s)://` forward proxy for the connection, e.g. `--proxy http://127.0.0.1:12334`; when given, `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` are ignored ([below](#through-a-forward-proxy)) |
+| `--header "Name: value"` | Repeatable. Extra header on the connection, for an auth proxy in front of the server |
+| `HALO_SHELL_TIMEOUT` | `node_run` timeout in ms (default 120000) |
+| `--version` / `--help` | Print the version / usage |
 
-The admin row turns green (live, no refresh) and shows `folder · shell on/off · os`.
+Exits 1 on a rejected / revoked token, a deleted workspace, a protocol mismatch or a bad flag; retries everything else.
 
 ### Folder mode vs whole-machine mode
 
 - **`--root <folder>`** — share one folder. Every path the agent passes must stay inside it (symlinks pointing out are refused too); relative paths start from it.
-- **No `--root`** (or `--root /`) — **whole-machine mode**: the agent can reach every path your user can, like a full-access local session. Relative paths start from the directory you ran `halo node` in. A startup line warns about it, and the admin shows "Whole machine".
+- **No `--root`** (or `--root /`) — **whole-machine mode**: the agent can reach every path your user can, like a full-access local session. Relative paths start from the directory you ran `halo-node` in. A startup line warns about it, and the admin shows "Whole machine".
 
 Prefer `--root` unless you really mean the whole machine.
 
 ### `--allow-shell`
 
-Off by default — `node_run` then refuses with "restart `halo node` with --allow-shell". With it, agents can run **any command as your user, not sandboxed**. In folder mode only the command's working directory is held inside the folder; the command itself (`cat ~/.ssh/...`, `curl ...`) can reach anything your user can. Turn it on only for agents and workspaces you trust. Commands are killed after the shell timeout (120 s, or `HALO_SHELL_TIMEOUT` in ms on the machine).
+Off by default — `node_run` then refuses with "restart `halo-node` with --allow-shell". With it, agents can run **any command as your user, not sandboxed**. In folder mode only the command's working directory is held inside the folder; the command itself (`cat ~/.ssh/...`, `curl ...`) can reach anything your user can. Turn it on only for agents and workspaces you trust. Commands are killed after the shell timeout (120 s, or `HALO_SHELL_TIMEOUT` in ms on the machine).
 
 ### What the agent can see
 
@@ -97,25 +102,41 @@ Everything inside the shared folder — including `.env` files, keys, credential
 
 ### Behind a login proxy
 
-`halo node` sends a bearer token, nothing else. If the server sits behind an auth proxy (Cloudflare Access, an SSO gateway, basic auth), either point `--server` at an address the machine can reach directly, or pass the proxy's credentials with `--header` (repeatable, `Name: value`, split on the first colon):
+`halo-node` sends a bearer token, nothing else. If the server sits behind an auth proxy (Cloudflare Access, an SSO gateway, basic auth), either point `--server` at an address the machine can reach directly, or pass the proxy's credentials with `--header` (repeatable, `Name: value`, split on the first colon):
 
 ```bash
 halo-node --server https://halo.example.com --root ~/proj \
   --header "CF-Access-Client-Id: <id>" --header "CF-Access-Client-Secret: <secret>"
 ```
 
-Neither client follows `HTTP(S)_PROXY`. To reach the server through a forward proxy, put a reverse proxy in front of the server instead, or use `--header`.
+### Through a forward proxy
+
+To send the connection out through a local or corporate proxy (Hiddify / Clash system proxy, a company HTTP proxy), pass `--proxy`:
+
+```bash
+halo-node --server https://halo.example.com --root ~/proj --proxy http://127.0.0.1:12334
+```
+
+`http://` and `https://` proxies only, `user:pass@` allowed (`--proxy http://alice:pw@proxy.corp:3128` — sent as `Proxy-Authorization`, never printed; the startup line shows only `scheme://host:port`). Percent-encode a `/`, `?`, `#` or `@` in the user or password (`%2F`, `%3F`, `%23`, `%40`); a URL with anything after the host is refused. Without `--proxy`, halo-node reads the usual environment variables — `HTTPS_PROXY` for an `https://` server, `HTTP_PROXY` for `http://`, `NO_PROXY` for exceptions:
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:12334 halo-node --server https://halo.example.com --root ~/proj
+```
+
+`--proxy` wins: when it's given, all three variables are ignored. A server on `localhost` / `127.0.0.1` is never proxied through the variables. Most system-proxy apps don't set these variables for the terminal, so pass one of the two explicitly. Conversely, a machine whose shell sets `HTTPS_PROXY` / `HTTP_PROXY` for other tools but reaches the server directly needs the server's host in `NO_PROXY` (halo-node before 2.2.4 ignored the variables).
+
+Use a `https://` server through a proxy. An `https://` (wss) connection is tunnelled with `CONNECT`, so the proxy sees only the host and the token stays inside TLS. An `http://` (ws) server is requested from the proxy as a plain absolute-form `GET` — the token passes through the proxy in clear text, and a proxy that doesn't forward the WebSocket `Upgrade` can't connect at all.
 
 ### TLS certificates (`https://` servers)
 
-`halo-node` trusts the system's CA store (the Windows certificate store on Windows; `/etc/ssl/certs/…` on Linux, where `SSL_CERT_FILE` / `SSL_CERT_DIR` can point it elsewhere). It falls back to a built-in Mozilla root set only on a system with no CA bundle at all. For a private or corporate CA, install it into the system store, or on Linux set `SSL_CERT_FILE`. `halo node` (Node.js) does the opposite: it uses Node's built-in roots plus `NODE_EXTRA_CA_CERTS`, and ignores the system store.
+`halo-node` trusts the system's CA store (the Windows certificate store on Windows; `/etc/ssl/certs/…` on Linux, where `SSL_CERT_FILE` / `SSL_CERT_DIR` can point it elsewhere). It falls back to a built-in Mozilla root set only on a system with no CA bundle at all. For a private or corporate CA, install it into the system store, or on Linux set `SSL_CERT_FILE`.
 
 ### Run it as a service (systemd)
 
 ```ini
 # /etc/systemd/system/halo-node.service
 [Unit]
-Description=halo node
+Description=halo-node
 Wants=network-online.target
 After=network-online.target
 
@@ -138,7 +159,7 @@ RestartPreventExitStatus=1
 WantedBy=multi-user.target
 ```
 
-Network drops, server restarts, a busy token (409) and a lockout (429) are handled inside the process, which keeps running, so `on-failure` is enough. Don't use `Restart=always`: it keeps restarting after a revoked token, and each restart is a failed login. After 5 failures in 15 minutes the server locks out that IP address, which blocks every machine connecting from it. ExecStart takes the path the install script printed. For the npm client, set `ExecStart=/usr/bin/halo node …`. After upgrading with the install script, `systemctl restart halo-node` to run the new binary.
+Network drops, server restarts, a busy token (409) and a lockout (429) are handled inside the process, which keeps running, so `on-failure` is enough. Don't use `Restart=always`: it keeps restarting after a revoked token, and each restart is a failed login. After 5 failures in 15 minutes the server locks out that IP address, which blocks every machine connecting from it. ExecStart takes the path the install script printed. After upgrading with the install script, `systemctl restart halo-node` to run the new binary.
 
 ### Start at boot on Windows (Task Scheduler)
 
@@ -170,7 +191,7 @@ If your server is reached through **Tailscale**, enable Tailscale's **Run unatte
 
 ### Settings on the machine
 
-`halo-node` takes its shell timeout only from `HALO_SHELL_TIMEOUT` (ms, default 120 s); grep's default of 50 matches and the 5 MiB command-output cap are fixed. `halo node` (npm) also reads them from the machine's own `~/.halo/secrets/` (`timeout.shell_exec` in `config.yaml`, the `general.limits.*` keys in `settings.yaml`). This only matters on a machine that also runs a halo server with those settings changed.
+`halo-node` takes its shell timeout only from `HALO_SHELL_TIMEOUT` (ms, default 120 s); grep's default of 50 matches and the 5 MiB command-output cap are fixed. It doesn't read a halo server's `~/.halo/secrets/` settings on the same machine.
 
 ## 3. Let the agent use it
 
@@ -193,8 +214,8 @@ Then just ask: "list my machines", "read `notes/todo.md` on mbp", "run the tests
 |---|---|
 | `token rejected by the server (401)` | Wrong / deleted token — create a new one. 5 bad tries in 15 min lock the address out for a while (429). |
 | `the workspace this token is bound to no longer exists (404)` | The workspace folder was removed on the server. |
-| `protocol mismatch (426)` | Client and server versions too far apart — upgrade the older side. |
-| `this token is already connected from another process` | Another `halo node` with the same token is running; this one keeps retrying until that one stops. Also normal right after the machine rebooted or woke from sleep: the server needs 40–60 s to notice the old connection is dead, so the new process backs off and can take up to ~90 s to come online. |
-| agent: `machine "mbp" is offline` | `halo node` isn't running / connected. |
+| `protocol mismatch (426)` | `halo-node` and the server speak different protocol versions — upgrade the older one: re-run `install.sh` (or download the server's release) here, or `halo upgrade` on the server. |
+| `this token is already connected from another process` | Another `halo-node` with the same token is running; this one keeps retrying until that one stops. Also normal right after the machine rebooted or woke from sleep: the server needs 40–60 s to notice the old connection is dead, so the new process backs off and can take up to ~90 s to come online. |
+| agent: `machine "mbp" is offline` | `halo-node` isn't running / connected. |
 | agent: `went offline during the call` | The connection dropped mid-call; the operation may or may not have happened. Running commands on the machine were stopped. |
 | agent: `not available in this runtime` | You're in the standalone CLI / TUI — linked machines only work through `halo server` (admin UI or a channel). |

package/bundled-docs/requirements/command.md

@@ -11,7 +11,7 @@ Top-level built-in slash commands: `/help` `/evo` `/session` `/agent` `/skill` `
 | Name | Slash | Type | Purpose |
 |---|---|---|---|
 | `help` | `/help` | server | List commands — object commands show only the verbs the user can run; a command is hidden entirely if no verb is runnable |
-| `evo` | `/evo [text]` | server | Flat command (no verbs), **full-only**. Trigger self-evolution on the current root session: snapshot the conversation + queue an evo run. Optional text becomes a hint for what to focus on. Works at every `general.evolution.level` (L0 = manual only; L1 also drafts automatically on pre-compact; L2 / L3 may also auto-apply the result — prompt-only / capability changes that pass the gates — then post one `chat:system` line in this session). Hidden from `/help` for non-full users. See [design/evolution.md](../design/evolution.md). |
+| `evo` | `/evo [text]` | server | Flat command (no verbs), **full-only**. Trigger self-evolution on the current root session: snapshot the conversation + queue an evo run. Optional text becomes a hint for what to focus on. Works at every `general.evolution.level` (L0 = manual only; L1 also drafts automatically on pre-compact; L2 / L3 may also auto-apply the result — prompt-only / capability changes that pass the gates — then post one `chat:system` line in this session). The level is the workspace's own: `evolution.level` can be set per workspace in `<ws>/.halo/settings.yaml`, falling back to the global one. Hidden from `/help` for non-full users. See [design/evolution.md](../design/evolution.md). |
 
 The rest are noun-verb **object commands**: `/<obj> <verb> [args]`. Some verbs are built-in deterministic code (`SUBCOMMAND_ROUTES`); the others fall through to the same-name skill (LLM, dispatched via `$1`). Bare `/<obj>` or `/<obj> help` lists the verbs available to the user (filtered by access level).
 

package/bundled-docs/requirements/settings.md

@@ -102,13 +102,49 @@ An installed canvas extension declares its own config in its manifest: `"setting
 
 ### General — built-in
 
-Declared in [packages/server/src/settings-schema.ts](../../../packages/server/src/settings-schema.ts) `generalSection()`. The server itself is the implicit declarer. Keys: `language`, `theme`, `agent.max_retries`, `server.*`, `session.*`, `compact.*`, `sandbox.*`, `logging.*`, `observability.*` (read once at boot — restart the server to apply; cron / evolution runs pick a change up on their next run), `evolution.*`, `limits.*`. All `general.*` keys are `globalOnly`: `config.ts` resolves them through `settingsValue()` against `~/.halo/secrets/settings.yaml` only, so a workspace `settings.yaml` cannot override them. Per-workspace layering applies to namespaced `params` / `secrets` (`getServerSecret(ns, key, workspaceRoot)`, `substituteSecrets`).
+Declared in [packages/server/src/settings-schema.ts](../../../packages/server/src/settings-schema.ts) `generalSection()`. The server itself is the implicit declarer. Keys: `language`, `theme`, `agent.max_retries`, `server.*`, `session.*`, `compact.*`, `sandbox.*`, `logging.*`, `observability.*` (read once at boot — restart the server to apply; cron / evolution runs pick a change up on their next run), `outbound_proxy.*`, `evolution.*`, `limits.*`. All `general.*` keys are `globalOnly` except `evolution.level` and `evolution.auto_apply_threshold`: `config.ts` resolves the `globalOnly` ones through `settingsValue()` against `~/.halo/secrets/settings.yaml` only, so a workspace `settings.yaml` cannot override them. Per-workspace layering applies to namespaced `params` / `secrets` (`getServerSecret(ns, key, workspaceRoot)`, `substituteSecrets`).
 
 `server.trust_proxy` (boolean, default `false`, `globalOnly`): whether the brute-force rate limiter (`middleware/brute-force.ts` `getClientIp`) trusts the `x-forwarded-for` header for client IP resolution. Direct-connect deployments leave it `false` and get the socket address. Behind a reverse proxy (nginx / Cloudflare / etc.), set it to `true` so the real client IP is honored instead of the proxy's — but only when that proxy is one you control and rewrites the header itself, otherwise a client can forge XFF to dodge lockouts.
 
 `sandbox.hidden_dirs` / `sandbox.hidden_files` / `sandbox.writable_dirs` are `globalOnly` — they define the security boundary agents run inside, so a workspace `settings.yaml` cannot override them (a workspace overriding them could lift its own sandbox constraints). `hidden_dirs` / `hidden_files` hold **extra** entries: the effective list is the built-in default (`DEFAULT_HIDDEN_DIRS` / `DEFAULT_HIDDEN_FILES` in `tools/sandbox.ts`, the single source — `~/.halo/secrets`, `~/.aws`, `~/.ssh`, `~/.gnupg`, `~/.docker`, `~/.config/gh`, `~/.halo/global/internal-sessions`, `~/.halo/global/logs`; `~/.npmrc`, `~/.bash_history`, `~/.gitconfig`, `~/.git-credentials`, `~/.netrc`, the global `evo` / `cron` / `runs` databases + `-wal` / `-shm`) plus the user's entries, deduped (`config.ts` `resolveSandboxPaths()`, used by both the server and the CLI). A default entry cannot be removed from the list in settings. The lists apply only to workspace / readonly sessions (bwrap / Seatbelt, or `assertPathAllowed` without an OS sandbox); Full sessions, the admin file explorer (`validatePath`, workspace-bound only) and the terminal never consult them. The schema `default` is empty so the placeholder doesn't suggest copying the built-ins; the field description names them. `writable_dirs` is a plain list (no built-ins).
 
-`evolution.*` controls the self-evolution subsystem (see [design/evolution.md](../design/evolution.md)). All `evolution.*` keys are `globalOnly` — they live in `~/.halo/secrets/settings.yaml` only, not workspace settings. Notable knobs: `evolution.level` (`L0` = manual only: `/evo` drafts, a reviewer approves; `L1` = L0 plus automatic drafting on pre-compact; `L2` = L1 plus auto-applying prompt-only changes that pass the gates; `L3` = L2 plus auto-applying capability changes — auto-applied changes still pass the regression check and can be rolled back from the Evolution tab; only changes learned from a `full`-access session auto-apply, never from one that took cron webhook events; a cron run's own turn never drafts on pre-compact), `evolution.auto_apply_threshold` (int 0–100, default 80 — minimum average score at L2/L3, on top of the fixed floors confidence high / behavior ≥ 70 / lint 100 / all sandbox checks; a save outside 0–100 is rejected with 400), `evolution.max_concurrent_run` / `max_concurrent_apply` (wrapper concurrency caps), `evolution.run_timeout_minutes` / `apply_timeout_minutes` (heartbeat timeouts), `evolution.max_attempts` (per-row retry cap), `evolution.triggers.pre_compact` (snapshot session before compaction).
+#### Outbound proxy
+
+For a machine whose way out is a local proxy (e.g. Hiddify / Clash in system-proxy mode on `127.0.0.1:12334`). Command-line tools ignore the OS proxy setting, so without this they connect directly. Three `globalOnly` fields, all read live (the mtime-cached settings, one `stat` per spawn / request) — no restart:
+
+| Key | Type | Default | Meaning |
+|---|---|---|---|
+| `outbound_proxy.enabled` | boolean | `false` | Master switch. On with an empty `url` = off, no error |
+| `outbound_proxy.url` | string | `''` (placeholder `http://127.0.0.1:12334`) | Proxy address. Must parse with scheme `http:` or `https:` and carry **no user-info** — `PUT` / `PATCH` reject `user:pass@…` with 400 (`… put them in Token …`) so a credential never lands in a plain-text field. A hand-edited bad value is ignored at read time (proxy off, one `[OutboundProxy]` warning that never echoes the URL) |
+| `outbound_proxy.token` | string, **secret** | `''` | Optional credential: `user:password`, or a bare token (= user name, empty password). Masked in `GET /api/settings/schema` like any secret |
+
+**What goes through it** (when on):
+- **Spawned children** — `shell_exec` at every access level, Terminals, notebook kernels, evolution runs. `cleanChildEnv()` (`child-env.ts`) adds `http_proxy`, `https_proxy`, `HTTP_PROXY`, `HTTPS_PROXY`, `no_proxy`, `NO_PROXY`. The bwrap (`--clearenv` + `--setenv`) and macOS Seatbelt (allowlisted env) paths add the same vars from the same function. Neither isolates the network, so a proxy on the host's loopback is reachable from inside.
+- **web_fetch** and **A2A requests to remotes** (agent card + JSON-RPC, `a2a/outbound.ts`) — an undici `ProxyAgent` passed per request. It is never the global dispatcher: model provider calls share the global `fetch` and keep their own route. A2A's `general.a2a.url_allowlist` check still runs on the target before the request goes to the proxy. A2A push webhooks to callers and inbound image URL fetches stay direct.
+
+**Not covered**: model provider calls, channel connections (Telegram / Slack / Feishu …), the hub / update checks.
+
+**no_proxy**: `localhost,127.0.0.1,::1`, plus whatever `NO_PROXY` / `no_proxy` the server process itself inherited, deduped (an inherited `*` makes the list just `*`). A child gets that list. web_fetch / A2A match it the way curl 8.x does, so in-process requests and a child's curl route alike:
+- a host name matches an entry equal to it or to a parent domain, case-insensitive, a leading dot ignored — `corp.example` and `.corp.example` both match `corp.example` and `a.corp.example`, not `notcorp.example`;
+- an IP address (v4, or v6 as in `http://[fd00::1]/`) matches an entry that is that address or a CIDR containing it — `10.0.0.0/8`, `fd00::/8`; an IP entry never matches a host name;
+- `*` alone matches everything;
+- nothing else is a pattern: `*.corp.example` is compared literally (matches no real host), and an entry with a port (`host:8080`) never matches — ports play no part.
+
+web_fetch applies this per redirect hop: a redirect into a no_proxy host connects directly, one out of it goes through the proxy.
+
+**Off** = Halo sets no proxy variables at all. Proxy variables the server process inherited from its own environment are not removed — they are the operator's.
+
+**Token transport** — Basic auth both ways, `base64(user:password)`:
+- children: in the proxy URL's user-info, percent-encoded (`http://<user>:<pass>@host:port`) — the one form curl, git and pip all read;
+- web_fetch / A2A: the `Proxy-Authorization` header (on the CONNECT for https and http alike). While the proxy is on, a web_fetch call carrying its own `Proxy-Authorization` header (any case) is refused with a tool error before any request — no_proxy targets included.
+
+`<<ENV_NAME>>` in the token expands from the server's environment, as in any secret; an unset variable stays literal.
+
+The credential never appears in logs (only the user-info-free origin is printed: `[OutboundProxy] on: http://host:port (with token)`). In `shell_exec` results (e.g. `env` output) its URL form `<user:pass>@` (percent-encoded or not) and its base64 are masked at any length; the bare token / encoded user-info on their own only from 4 characters (shorter strings would mangle ordinary output). In bwrap sessions only the command itself gets the proxy variables, not the file tools' helper processes.
+
+**Terminals** get their env when they are opened: a Terminal already open keeps the old setting, a newly opened one picks up the change.
+
+`evolution.*` controls the self-evolution subsystem (see [design/evolution.md](../design/evolution.md)). `evolution.level` and `evolution.auto_apply_threshold` can be set **per workspace**: `<workspace>/.halo/settings.yaml` overrides `~/.halo/secrets/settings.yaml`, which overrides the schema default (an open workspace can sit at L0 while a private one auto-applies), and the workspace Settings page edits them like any non-`globalOnly` field. The rest of `evolution.*` is `globalOnly` — it lives in `~/.halo/secrets/settings.yaml` only, not workspace settings. Notable knobs: `evolution.level` (`L0` = manual only: `/evo` drafts, a reviewer approves; `L1` = L0 plus automatic drafting on pre-compact; `L2` = L1 plus auto-applying prompt-only changes that pass the gates; `L3` = L2 plus auto-applying capability changes — auto-applied changes still pass the regression check and can be rolled back from the Evolution tab; only changes learned from a `full`-access session auto-apply; a cron run's own turn never drafts on pre-compact), `evolution.auto_apply_threshold` (int 0–100, default 80 — minimum average score at L2/L3, on top of the fixed floors confidence high / behavior ≥ 70 / lint 100 / all sandbox checks; a save outside 0–100 is rejected with 400), `evolution.max_concurrent_run` / `max_concurrent_apply` (wrapper concurrency caps), `evolution.run_timeout_minutes` / `apply_timeout_minutes` (heartbeat timeouts), `evolution.max_attempts` (per-row retry cap), `evolution.triggers.pre_compact` (snapshot session before compaction).
 
 Goal mode's entry points are offline (the `/goal` command, admin banner and creation of new goal sessions are hidden). To reopen them, set `general.goal_mode_enabled` — a global-only boolean, default `false`, read from `~/.halo/secrets/settings.yaml` only (a workspace `settings.yaml` has no effect) and not shown in the Settings UI — then restart the Halo server and refresh the browser (existing goal bindings and history are not touched either way):
 
@@ -134,6 +170,7 @@ There is no "default provider" setting: a newly created agent's `model:` is a co
 | `options` / `optionLabels` | no | For `type: enum`: the allowed values, and optional display labels parallel to them |
 | `description` | no | English description rendered as help text |
 | `description_zh` | no | Chinese description (UI picks based on lang) |
+| `placeholder` | no | Example shown in an empty text input, display only — unlike `default` it is not a value anything falls back to (e.g. `outbound_proxy.url`). Built-in `general` section only |
 | `default` | no | Placeholder shown when the value is unset; supports `<<ENV>>`. For provider / skill / agent fields it is display-only: an unset param's `{{<id>.params.<key>}}` stays literal at substitution, so the consumer applies its own fallback (the `extension` skill's `ext.sh` treats `{{…}}` as "use the default hub"; `web-search`'s `search.py` as "use the default region") |
 | `secret` | no | `true` → masked in API responses + password input in UI |
 | `restartRequired` | no | `true` → read once at server start; the Settings page shows a restart notice after saving it. Built-in `general` section only |