@turmind/halo 0.1.9 → 0.2.1-bc7cf2b

package/bundled-docs/dev/acp-adapter.md

@@ -43,7 +43,7 @@ Claude Code on a developer's laptop wants to talk to a halo agent running in an
 
 The most common use of this adapter isn't a third-party ACP client — it's *another halo agent* calling out over ACP. Halo ships a builtin skill `acp` (slash command `/acp`, full access). Its bundled `templates/ask.py` is a unified ACP client; `--kind` picks the peer:
 
-- `halo` (default) — spawns `halo acp --host --port --token --workspace` (this adapter) to reach a **remote halo server**
+- `halo` (default) — spawns `halo acp --host --port --scheme --token --workspace` (this adapter) to reach a **remote halo server** (`--scheme` optional, default `http`; pass `https` for a TLS-fronted server)
 - `claude` — spawns `claude-agent-acp` (npm `@agentclientprotocol/claude-agent-acp`): local Claude Code, zero config, just `--cwd`
 - `kiro` — spawns `kiro-cli acp --trust-all-tools`: local Kiro, zero config `--cwd`, optional `--agent-id`
 
@@ -58,7 +58,7 @@ The question text reaches the peer **verbatim — including the peer's own slash
 
 ### `ask-*` bindings — the multi-remote-halo path
 
-Remote halo servers are **not** a direct verb: each remote needs its own host/token/workspace, so `/acp add` walks the user through (label, host, port, workspace, token), then **stamps out a new skill** named `ask-<label>` containing:
+Remote halo servers are **not** a direct verb: each remote needs its own host/token/workspace, so `/acp add` walks the user through (label, host, port, scheme, workspace, token), then **stamps out a new skill** named `ask-<label>` containing:
 
 - `SKILL.md` — slash command `/ask-<label>`, instructions tailored to this remote
 - `config.yaml` — declares the binding's params so admin Settings shows a form
@@ -77,12 +77,39 @@ To remove a binding: `/acp remove` (deletes the skill directory and points out t
 |------------------|----------|------------------------------------------------------------------------------------------|
 | `--host`         | yes      | Halo server hostname / IP (e.g. `localhost`, `ec2-1-2-3-4.compute…`).                  |
 | `--port`         | yes      | Halo server port (e.g. `9527`).                                                        |
+| `--scheme`       | no       | URL scheme — `http` or `https` (default `http`). Use `https` when the server sits behind a TLS reverse proxy. Invalid values are rejected at the adapter boundary. |
 | `--token`        | yes      | Web-channel token from admin UI. `full` access required for multi-workspace use.         |
 | `--workspace`    | yes      | Absolute server-side path for the workspace this adapter drives.                         |
 | `--agent-id`     | no       | Halo agent profile to use when ACP `session/new` creates a new halo session. Default: `default`. |
+| `--header`       | no       | Extra HTTP header on every upstream request, `"Name: value"` (like `curl -H`). Repeatable. For auth that sits **in front of** the halo server — see "Upstream auth" below. |
 
 One adapter process binds to one workspace. To drive multiple workspaces concurrently from the same token, run multiple adapter processes — see "Multi-workspace" below.
 
+## Upstream auth (`--header`)
+
+`--token` authenticates the adapter to *halo itself* (it becomes the `x-token` header on every web-channel call). It does **not** cover a proxy sitting in front of the server — an SSO/session-cookie gateway, Cloudflare Access, ALB OIDC, nginx basic-auth. Those reject the request before halo ever sees the token.
+
+`--header` is the generic escape hatch: it forwards arbitrary headers on every request the adapter makes (`/api/web/chat`, `/history`, `/stop`), exactly like `curl -H`. The adapter deliberately knows nothing about any specific gateway — you supply whatever that layer wants:
+
+```sh
+# session-cookie gateway
+halo acp --host h --port 9527 --scheme https --token <t> --workspace /ws \
+  --header "Cookie: <the gateway's session cookie, verbatim>"
+
+# Cloudflare Access (two headers — --header is repeatable)
+halo acp … --header "CF-Access-Client-Id: <id>" --header "CF-Access-Client-Secret: <secret>"
+
+# HTTP basic auth
+halo acp … --header "Authorization: Basic <base64 user:pass>"
+```
+
+Notes:
+
+- **Repeatable** — pass `--header` as many times as the gateway needs.
+- **Colon-safe** — the value is split on the *first* `:` only, so header values that themselves contain colons (`Cookie: a=b:c`) survive intact.
+- **`x-token` always wins** — `--header` cannot override the adapter's own `x-token` / `content-type`; it only adds headers for the layer in front of halo.
+- The generated `ask-<label>` bindings (halo→halo, via `ask.py`) do **not** yet expose `--header`; upstream auth through a binding isn't wired. `halo acp` direct is the path when a gateway is in play.
+
 ## ACP method coverage
 
 | Method              | Implemented? | Notes                                                                  |
@@ -299,7 +326,7 @@ halo cli -a default -n -w /home/ubuntu/halo-test \
   '/acp add 参数：label=foo，host=localhost，port=9527，workspace=/home/ubuntu/sa-agent，token=<token>，scope=workspace。不要问后续问题，全自动创建。'
 ```
 
-Expect: agent creates `.halo/skills/ask-foo/{SKILL.md,config.yaml,ask.py}`, writes `ask-foo` block to `<workspace>/.halo/settings.yaml` with **all 5 user values** (host/port/workspace/label/token), wires the binding into the current agent's skills list. Reply confirms the four paths.
+Expect: agent creates `.halo/skills/ask-foo/{SKILL.md,config.yaml,ask.py}`, writes `ask-foo` block to `<workspace>/.halo/settings.yaml` with **all 5 user values** (host/port/workspace/label/token) plus `scheme: http` (defaulted — the prompt omits it), wires the binding into the current agent's skills list. Reply confirms the four paths.
 
 **4.2 invoke the freshly-generated binding**
 
@@ -321,7 +348,7 @@ rm -rf /home/ubuntu/halo-test/.halo/skills/ask-foo
 
 Open admin → Settings → Skills → **Ask SA Agent** (or whichever binding):
 
-**5.1** All 6 fields render: `host`, `port`, `workspace`, `label`, `agent_id`, `token` (with mask icon).
+**5.1** All 7 fields render: `host`, `port`, `scheme`, `workspace`, `label`, `agent_id`, `token` (with mask icon).
 
 **5.2** Each field's source label says **workspace** (not "继承自 global"), because values live in `<halo-test>/.halo/settings.yaml`.
 

package/bundled-docs/dev/api.md

@@ -235,10 +235,12 @@ runtime so the frontend can render rooms (workspaces) + characters (sessions).
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/show/state` | Full-access token → every known workspace; otherwise the account's own. Returns `{ serverTime, uptime, accessLevel, skills[], workspaces[] }` |
-| GET | `/api/show/session?ws=&id=` | Inspector-panel detail for a single session. Trimmed message log (last 40, content/tool I/O capped) plus `contextTokens` / `outputTokens` / `maxContextTokens` / `isRunning`. Non-full tokens may only read their own workspace. |
+| GET | `/api/show/state` | `full` or `observer` token → every known workspace; otherwise the account's own. Returns `{ serverTime, uptime, accessLevel, skills[], workspaces[] }` |
+| GET | `/api/show/session?ws=&id=` | Inspector-panel detail for a single session. Trimmed message log (last 40, content/tool I/O capped) plus `contextTokens` / `outputTokens` / `maxContextTokens` / `isRunning`. Non-`full`/`observer` tokens may only read their own workspace. |
 
-Each `workspace` = `{ path, key, label, counts{running,idle,stopped}, totalSessions, skills[], sessions[] }`; each `session` = `{ id, parentId, depth, agentName, description, status, lastTool, activeSkill, contextTokens, outputTokens, updatedAt }`. `lastTool` / `activeSkill` come from the live in-memory UI log (empty when the session isn't loaded). Sessions per room are capped (`totalSessions` reports the true total). Frontend: `halo-city/` at repo root.
+Each `workspace` = `{ path, key, label, counts{running,idle,stopped}, totalSessions, skills[], sessions[] }`; each `session` = `{ id, parentId, depth, agentName, description, status, lastTool, activeSkill, contextTokens, outputTokens, messageCount, updatedAt }`. `lastTool` / `activeSkill` come from the live in-memory UI log (empty when the session isn't loaded). Sessions per room are capped (`totalSessions` reports the true total). Frontend: `halo-city/` at repo root.
+
+**Read-only by construction — degraded snapshots.** Both endpoints resolve a workspace's runtime via `registry.peek()` — in-memory lookup only, **never** `getOrCreate`: constructing a SessionManager has write side effects (boot orphan-reconciliation batch-stops live sub-session rows; `.halo/` scaffolding), so a pure visualization poll must not trigger it. When no live SessionManager exists in this process, the handler opens that workspace's `.halo/halo.db` **read-only** (cached connection; missing db/tables silently degrade to an empty room) and projects rows / the persisted session file into the same wire shape. Sessions not in memory therefore return a **persisted snapshot**: `status` / token counts / `messageCount` may lag behind the last persistence point, and the live-only signals (`lastTool` / `activeSkill`) are empty by definition. The degraded `/api/show/session` path reports `maxContextTokens: 0` (the real cap needs a live agent config; the city inspector hides the meter when the cap is unknown).
 
 ## Agent Configs
 
@@ -312,7 +314,7 @@ File: `packages/server/src/routes/evolution.ts`. Surfaces the global `evolution_
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/api/evolution/runs` | List all evolution runs across workspaces. Carries the latest `apply_id`/`apply_status` per run. (Score isn't surfaced in the list — it's read from `score.json` on the detail fetch only.) |
-| GET | `/api/evolution/runs/:id` | Detail: db row + `patch.md` + `score.json` + `system-suggestions.md` (optional, evo writes when it has platform-level feedback) + `.skip.md` (when `status='skipped'`) + a snapshot summary (first user message + first assistant reply + message count). |
+| GET | `/api/evolution/runs/:id` | Detail: db row + `patch.md` + `score.json` + `.skip.md` (when `status='skipped'`) + wrapper/sub-cli logs + a snapshot summary (first user message + first assistant reply + message count). Row carries `failureReason` (and `applyFailureReason` from the latest apply) — apply-side values include `phase A': apply cli exited <code>`, `phase A': apply agent aborted: <first line of ABORT.md>`, and `phase A': apply agent didn't produce apply.log`. |
 | POST | `/api/evolution/runs/:id/approve` `{reviewerHint?}` | Move run from `awaiting_review` → `approved`, insert a pending `evolution_applies` row that the ticker will pick up. |
 | POST | `/api/evolution/runs/:id/reject` | Move run from `awaiting_review` → `rejected`. |
 | POST | `/api/evolution/runs/:id/retry` `{hint}` | Reset a finished run back to `pending` with the supplied (required) hint so the wrapper picks it up again. Rejected with 409 when the run is already `running` / `pending`. |

package/bundled-docs/dev/desktop-packaging.md

@@ -1,9 +1,12 @@
 # Desktop Packaging (Electron / DMG)
 
-How to build the macOS desktop app (`Halo-0.1.5-arm64.dmg`). The desktop
-build is a thin Electron shell (`packages/desktop`) that bundles a self-
-contained server runtime + a private `node` binary + the admin static export,
-then spawns the server as a child process and points a `BrowserWindow` at it.
+How to build the desktop app. We ship two artifacts: **Windows x64**
+(`Halo Setup <ver>.exe`, built on a Linux host) and **macOS arm64**
+(`Halo-<ver>-arm64.dmg`, built on Apple Silicon) — see the target matrix
+below. The desktop build is a thin Electron shell (`packages/desktop`) that
+bundles a self-contained server runtime + a private `node` binary + the admin
+static export, then spawns the server as a child process and points a
+`BrowserWindow` at it.
 
 See [design](../design/) for the server itself; this doc is only about the
 packaging pipeline.
@@ -36,6 +39,13 @@ one.
 
 ```bash
 cd packages/halo   # repo root
+# 0. VERSION GATE — confirm every package is on the release version BEFORE
+#    building or tagging. The five packages must move in lockstep; a single
+#    lagging one ships a mismatched build and a wrong `halo --version`.
+for f in packages/{core,server,admin,cli,desktop}/package.json; do
+  printf "%-32s " "$f:"; grep -m1 '"version"' "$f"
+done   # all five must read the same x.y.z, and match the tag you're about to cut
+
 # 1. build the upstream artifacts the stage script consumes, IN ORDER.
 #    - core MUST build before server: server imports @turmind/halo-core
 #      (e.g. GitManager in routes/git.ts). A stale/missing core/dist makes
@@ -46,6 +56,10 @@ cd packages/halo   # repo root
 pnpm --filter @turmind/halo-core build
 pnpm --filter @turmind/halo-server build
 pnpm --filter @turmind/halo-admin build
+# NOTE: acp-adapter is NOT listed here on purpose — build-bundle.mjs now
+# builds every workspace:* dep (core / server / acp-adapter) itself before
+# esbuild inlines them, so its dist can't go stale. This block only covers
+# artifacts the stage script consumes directly (server dist, admin-out).
 
 # 2. stage + package (arm64)
 cd packages/desktop
@@ -58,8 +72,47 @@ Output: `packages/desktop/dist/Halo-0.1.5-arm64.dmg` (~143 MB).
 `gen-icon` → `prepack-dmg` (`scripts/stage-runtime.mjs`) → `electron-builder
 --mac --arm64`.
 
-Other targets: `pnpm dist:x64` (Intel mac), `pnpm dist:win` (Windows nsis,
-cross-staged from mac).
+## Release target matrix (current policy)
+
+Two shipped artifacts per release, each built on its native-ish host:
+
+| Target | Host we build on | Command | Notes |
+|--------|------------------|---------|-------|
+| **Windows x64** (`Halo Setup <ver>.exe`, nsis) | **Linux x86_64** | `HALO_STAGE_FULL=1 CI=true pnpm dist:win` | host arch == target arch (x64), so native fixups are low-risk. This is now the standard path — *not* cross-staged from mac. |
+| **macOS arm64** (`Halo-<ver>-arm64.dmg`) | macOS (Apple Silicon) | `CI=true pnpm dist:arm64` | Apple Silicon only. |
+
+**`pnpm dist:x64` (Intel mac) is retired — we no longer ship an Intel build.**
+The `dist:x64` script still exists in `package.json` but is not part of any
+release; don't cut one.
+
+### Building the Windows exe on Linux (the standard path)
+
+```bash
+# from repo root — build upstream artifacts in order (see step 1 below), then:
+cd packages/desktop
+HALO_STAGE_FULL=1 CI=true pnpm dist:win
+```
+
+`HALO_STAGE_FULL=1` is **mandatory** here: a cross-stage must re-run the
+per-target native fixups (`@parcel/watcher-win32-x64` swap, `better-sqlite3`
+win prebuild), which the fast path skips. `wine` must be installed (electron-
+builder runs the nsis maker through it).
+
+Verified on the v0.1.9 build (Linux x86_64 host → win-x64):
+- **No poisoned arm64 dmg to discard.** Unlike a mac host, a Linux `--win` run
+  never triggers the yml's mac target — `dist/` contains only `Halo Setup
+  <ver>.exe` + `.exe.blockmap` + `win-unpacked/`. The "discard the stray
+  arm64 dmg" gotcha below is mac-host-only.
+- **Native arch check** — every staged `.node` must be PE32+ x86-64, no ELF:
+  `find dist/win-unpacked -path '*watcher-*' -name '*.node' | xargs file` and
+  `file dist/win-unpacked/resources/node.exe` (should read `PE32+ ... x86-64`).
+- **Two benign warnings**, both expected: `file source doesn't exist
+  from=.../resources/node` (win bundles `node.exe`, not the Unix `node` — the
+  yml lists both, electron-builder skips the absent one) and `signing is
+  skipped` (no Windows code-sign cert). Neither fails the build.
+
+> A `desktop-packaging.local.md` (gitignored, per-host) may carry extra
+> machine-specific setup — read it first if present.
 
 ## Faster rebuilds
 
@@ -138,8 +191,10 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
 2. **Copy `templates/`** — `pnpm deploy` doesn't pick these up; copied
    explicitly. This is what carries the built-in skills (incl. `send-file`),
    agents, prompts, models into the dmg.
-3. **Cross-arch native fixup** — when target arch/platform ≠ host, re-fetch
-   `better-sqlite3` prebuilds via `prebuild-install`.
+3. **Native fixup** — re-fetch `better-sqlite3` prebuilds via `prebuild-install
+   --target=22.11.0` **unconditionally** (pins the ABI to the bundled node
+   regardless of the build host's node — see the ABI gotcha below);
+   `@parcel/watcher`'s per-platform binary is swapped only when cross-staging.
 4. **Trim bloat** — drop non-target `node-pty` prebuilds, `better-sqlite3`'s
    C source, and the server's `src/`/`tests/`.
 5. **Copy `admin-out/`** — the Next.js static export.
@@ -147,6 +202,9 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
    nodejs.org, extract the `node` binary into `resources/`.
 7. **codesign (ad-hoc)** — `codesign --force --sign -` on the node binary for
    Gatekeeper. **We deliberately do NOT `strip`** — see gotcha below.
+8. **Native-addon smoke test** — load the staged better-sqlite3 with the
+   bundled node binary; abort the build if it can't `dlopen` (the ABI backstop,
+   runs on full and fast paths). See the ABI gotcha below.
 
 ## Gotchas (learned the hard way)
 
@@ -178,6 +236,28 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   looks fine but won't boot. Keep the full ~114 MB binary; the ~30 MB saved
   isn't worth a dead app. (`stage-runtime.mjs` has the strip step removed.)
 
+- **better-sqlite3's ABI must match the BUNDLED node (22.11.0 / ABI 127), not
+  the build host's node.** `pnpm deploy` / `npm install` hard-link whatever
+  `.node` the build host's *active* node produced. If a homebrew/nvm node 23
+  (ABI 131) shadows the pinned 22 on the build machine, the staged
+  `better_sqlite3.node` is ABI 131 — but the app runs it on the bundled node 22,
+  so it dies at launch with `NODE_MODULE_VERSION 131 ... requires 127`
+  (`ERR_DLOPEN_FAILED`, server `code=1`). The dmg packages fine and runs on the
+  builder's own machine (whose node happens to match), so it ships broken to
+  everyone else. Three guards now prevent this, all in `stage-runtime.mjs`:
+  1. `fetchTargetArchNatives()` runs `prebuild-install --target=22.11.0` for
+     better-sqlite3 **unconditionally** (not just when cross-staging), so the
+     ABI is always re-pinned to the bundled node regardless of the host node.
+  2. An early gate aborts if the build host's node major ≠ the bundled major
+     (`nvm use 22` then rebuild; override with `HALO_SKIP_NODE_CHECK=1`).
+  3. `smokeTestNativeAddons()` loads the staged better-sqlite3 with the bundled
+     node binary at the end of every stage (full AND fast) and aborts the build
+     if it can't `dlopen` — the final backstop no matter how a bad ABI crept in
+     (wrong host node, a fast path reusing a stale tree, a future native dep).
+  Verify a built dmg manually: `"<app>/Contents/Resources/node" -e
+  "new (require('<app>/Contents/Resources/server-runtime/node_modules/better-sqlite3'))(':memory:')"`
+  should exit 0.
+
 - **Desktop port is sequential from 9527 (NOT random), and that's load-bearing
   for persistence.** `main.cjs` `findFreePort()` tries 9527 first, then scans
   upward for the first free one, and passes it to the server child. It used to
@@ -236,6 +316,16 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   with `&& node scripts/copy-monaco.mjs`. If you must run `next build`
   directly, append the copy step yourself.
 
+- **All five package versions must move in lockstep — check before building or
+  tagging.** `core` / `server` / `admin` / `cli` / `desktop` each carry their own
+  `version` in `package.json`, and nothing auto-syncs them. When cutting 0.1.9,
+  `cli` + `desktop` were already bumped by hand but `server` sat at 0.1.8 and
+  `core` / `admin` at 0.1.0 — a `git tag` then would have shipped a build whose
+  `halo --version` (stamped from `package.json`) disagreed with the tag. The
+  step-0 version gate in "One-shot build" loops over all five so a lagging one is
+  caught before the tag is cut. (npm only publishes `cli` as `@turmind/halo`, but
+  the others feed `halo --version` / the admin sidebar, so they still matter.)
+
 - **Changing anything under `templates/` requires bumping `TEMPLATE_VERSION`
   (`packages/server/src/init.ts`) — otherwise the change never reaches existing
   installs.** Server startup only re-runs `ensureHaloHome` (the template

package/bundled-docs/dev/env.md

@@ -87,7 +87,7 @@ Source: `packages/server/src/config.ts`
 | Variable | Default | Config path | Description |
 |---|---|---|---|
 | `HALO_PORT` | `9527` | `config.yaml server.port` | Hono listen port |
-| `HALO_PASSWORD` | (none) | `config.yaml server.password` (scrypt hash) | Plaintext login password. When set, takes precedence over the stored hash and bypasses scrypt entirely — intended for Docker / systemd / CI. The hash is set by `halo setup` for interactive installs. |
+| `HALO_PASSWORD` | (none) | `config.yaml server.password` (scrypt hash) | Plaintext login password. When set, takes precedence over the stored hash and bypasses scrypt entirely — intended for Docker / systemd / CI. It also satisfies the **startup gate**: the server refuses to boot with no password configured, and env plaintext counts as a first-class credential there, so an env-only deployment (`halo setup -y && HALO_PASSWORD=... halo server start`, no stored hash) boots fine. The hash is set by `halo setup` for interactive installs. |
 | `HALO_CORS_ORIGINS` | empty (reflect any origin) | `config.yaml server.cors_origins` | CORS allowlist (comma-separated). Empty = reflect any incoming Origin so credentials work cross-origin. Set explicit list to enforce strict CORS. |
 | `HALO_FRONTEND_DIR` | `packages/admin/out` | — | Static frontend dir (resolved as absolute path from project root) |
 | `HALO_MAX_CONTEXT_TOKENS` | `200000` | — | Model max context |
@@ -117,6 +117,8 @@ settings.yaml only (no env override):
 - `kimi.secrets.api_key` — Kimi (Moonshot AI)
 - `deepseek.secrets.api_key` — DeepSeek
 
+When a provider manifest declares a `default: <<NAME>>` for a secret, `halo setup` offers a "Use env $NAME" action. Picking it **writes the literal `<<NAME>>` placeholder into settings.yaml**, which the standard env-var interpolation ([storage.md](../design/storage.md#env-var-interpolation-env_name)) expands against `process.env` at read time. There is no separate runtime env fallback — the placeholder in the file is the only mechanism (an unset env var leaves the literal `<<NAME>>` visible in the request, failing loudly).
+
 `<skill-id>.params.*` (referenceable from skills via `{{<skill-id>.params.<key>}}`, or short form `{{params.<key>}}` inside SKILL.md; declared in `skills/<id>/config.yaml`):
 - `tavily-search.params.api_key` — example only; declared by whichever skill needs it
 
@@ -136,7 +138,7 @@ settings.yaml-driven `general.limits.*` (no env override):
 Two ways to authenticate:
 
 1. **Interactive** — run `halo setup`, pick "Set / change password". The value is scrypt-hashed and written to `~/.halo/secrets/config.yaml server.password`. Best for personal installs.
-2. **Env** — export `HALO_PASSWORD=...` before launching the server. The plaintext value is compared directly (no hashing) and takes precedence over any stored hash. Best for Docker / systemd / CI where a secrets manager already protects the env.
+2. **Env** — export `HALO_PASSWORD=...` before launching the server. The plaintext value is compared directly (no hashing) and takes precedence over any stored hash. A stored hash isn't required at all — env plaintext alone satisfies the startup gate, so env-only deployments are legal. Best for Docker / systemd / CI where a secrets manager already protects the env.
 
 ## Verify
 

package/bundled-docs/dev/previews.md

@@ -27,6 +27,9 @@ previews/
     ├── docx.tsx / docx-view.tsx
     ├── xlsx.tsx / xlsx-view.tsx
     ├── pptx.tsx / pptx-view.tsx
+    ├── pptx-notes.ts         pptx zip helpers: speaker-notes extraction (jszip +
+    │                         DOMParser, play order via sldIdLst) + Content_Types
+    │                         repair for decks with dangling Override parts
     └── media.tsx / media-view.tsx
 ```
 

package/bundled-docs/dev/tools.md

@@ -181,6 +181,8 @@ Start a sub-agent session asynchronously. When the sub-agent finishes, its **wra
 - Depth exceeded: `{"code": 1, "error": "Maximum nesting depth (N) reached..."}`
 - Working dir invalid: `{"code": 1, "error": "working_dir \"...\" is outside the workspace"}` (or does-not-exist / not-a-directory)
 
+UI note: the `agent_start` event this emits carries both a 200-char `text` preview (parent-side rendering) and the full un-truncated brief as `fullText`, which seeds the sub-session log's opening user message — so viewing the child session shows the complete task brief (`system_prompt_context` + `message`), not a cut-off preview. See [session.md → Event routing](../design/session.md#event-routing).
+
 ### session_list
 
 List direct child sessions of the current session and their status.
@@ -293,7 +295,7 @@ Returns: full SKILL.md content (body + resource files list). For progressive dis
 |---|---|---|---|
 | `content` | string | yes | The complete draft answer. Required and must be non-empty |
 
-The tool **description is deliberately plain** — "Submit a draft answer for self-review; returns a checklist that critiques the draft." It does NOT say *when* to call it (no "call this for complex questions / when unsure"). An earlier version that did embed such self-referential guidance made some models (notably GPT-5.x) thrash. Steering toward *using* draft belongs in the agent's `system_prompt` (e.g. the bundled `default` agents say "hold your answers to a high standard… don't reply off the cuff"), not in the tool description. Empty `content` is rejected with an error **without consuming a draft round**.
+The tool **description is deliberately plain** — "Submit a draft answer for self-review; returns a checklist that critiques the draft." It does NOT say *when* to call it (no "call this for complex questions / when unsure"). An earlier version that did embed such self-referential guidance made some models (notably GPT-5.x) thrash. Steering toward *using* draft belongs in the agent's prompt files (the bundled `default` agent's AGENT.md says "hold your answers to a high standard… don't reply off the cuff" — it lives in AGENT.md because the yaml `system_prompt` is only a fallback when the MD layer is empty), not in the tool description. Empty `content` is rejected with an error **without consuming a draft round**.
 
 **Why it exists:** the agent loop only makes another model call when the model emits a `tool_use` block. A plain-text answer (`end_turn`) is single-pass — `thinking` runs *before* the answer in the same call, so the model never gets to look at its *finished* answer and revise it. `draft` closes that gap without touching the loop: the model writes its answer into `content` (materialised into the conversation as a `tool_use` block — uncapped, never echoed back), and the tool_result hands back an adversarial review checklist (framed as a hostile reviewer: list every factual claim and tag its source, verify the unverified ones with tools *now*, check directness/tone, flag gaps). The next model call then critiques that now-concrete draft and either revises (calls `draft` again) or writes the final answer.
 

package/bundled-docs/guide/cli.md

@@ -46,12 +46,14 @@ End users then install with `npm install -g @turmind/halo`.
 Run a one-shot prompt and exit:
 
 ```bash
-halo "review this PR"
-halo -w /path/to/workspace "analyze code"
-echo "review the changes" | halo
-cat prompt.txt | halo -w /path/to/review-ws
+halo cli "review this PR"
+halo cli -w /path/to/workspace "analyze code"
+echo "review the changes" | halo cli
+cat prompt.txt | halo cli -w /path/to/review-ws
 ```
 
+To list agents or sessions without running a prompt, use the dedicated subcommands `halo agents` / `halo sessions` (same `-w` flag).
+
 ### Options
 
 | Flag | Short | Default | Description |
@@ -59,11 +61,10 @@ cat prompt.txt | halo -w /path/to/review-ws
 | `--workspace` | `-w` | cwd | Workspace path |
 | `--agent` | `-a` | `default` | Agent ID |
 | `--session` | `-s` | auto | Resume session by ID |
+| `--new` | `-n` | off | Always start a new session |
 | `--format` | `-f` | `text` | Output format: `text` or `json` |
 | `--verbose` | `-v` | off | Show thinking, tool calls, usage on stderr |
 | `--access` | | `full` | Access level: `full`, `workspace`, `readonly` |
-| `--agents` | | | List available agents and exit |
-| `--sessions` | | | List recent sessions and exit |
 | `--lang` | | `en` | Language: `en` or `zh` |
 
 ### Output
@@ -91,21 +92,22 @@ cat prompt.txt | halo -w /path/to/review-ws
 
 ```bash
 # Code review in CI
-halo -w /path/to/review-ws "review the diff" --format json | jq '.text'
+halo cli -w /path/to/review-ws "review the diff" --format json | jq '.text'
 
 # Pipe content in
-git diff HEAD~1 | halo -w /path/to/review-ws "review this diff"
+git diff HEAD~1 | halo cli -w /path/to/review-ws "review this diff"
 
 # Exit code: 0 = success, 1 = error, 130 = SIGINT
-halo "check for issues" && echo "OK" || echo "FAILED"
+halo cli "check for issues" && echo "OK" || echo "FAILED"
 ```
 
 ## TUI Mode (interactive)
 
 ```bash
-halo -i
-halo -i -w /path/to/workspace
-halo -i -s sid_abc123   # resume session
+halo tui
+halo tui -w /path/to/workspace
+halo tui -s sid_abc123   # resume session
+halo tui -n              # always start a new session
 ```
 
 Multi-turn conversation. Supports all standard Halo slash commands:
@@ -130,6 +132,16 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | `/evo [hint]` | Queue a self-evolution run on this session (full access only) |
 | `/quit` | Exit |
 
+TUI-only client commands (handled locally, also visible in the completion popup):
+
+| Command | Description |
+|---|---|
+| `/clear` | Start a new session (alias for `/session new`) |
+| `/retry` | Resend the last user message |
+| `/verbose` | Toggle verbose tool output (args + truncated results) at runtime — same as launching with `-v`; the status bar shows a `v` badge while on |
+| `/log` | Browse the session tree and view a session log (same as `Ctrl+O`) |
+| `/exit` | Alias for `/quit` |
+
 Bare `/<obj>` (or `/<obj> help`) lists the verbs you may run. Verbs gated above your access level are hidden.
 
 ### Keybindings
@@ -139,9 +151,15 @@ Bare `/<obj>` (or `/<obj> help`) lists the verbs you may run. Verbs gated above
 | `Esc` (while running) | Interrupt the current turn immediately — aborts a command mid-execution, then any messages typed while it was running are folded into one follow-up turn. Same as `/session interrupt`. |
 | `Ctrl+C` | Graceful exit; press twice to force |
 | `Ctrl+O` | Toggle the sub-agent navigator — lists every sub-agent spawned this session, each showing its agent name, task title (same as the session list), and status (`●` running green / `○` idle grey / `✕` stopped red, plus a `▢ archived` marker when the session is archived); `↑↓` to move, `Enter` to view that sub-agent's log, `Esc`/`q` to close. (Was `Shift+Tab`, but Windows terminals consume that as backtab.) The log viewer auto-refreshes while the viewed session is still running (a `● live` hint shows in the header) and follows the bottom as new output lands — unless you've scrolled up to read, in which case it stays put (`G` jumps back to the bottom and resumes following). |
-| `↑` / `↓` | Walk input history (when no popup is open) |
+| `↑` / `↓` | Walk input history (when no popup is open). History persists across restarts in `~/.halo/global/tui-history.json` (last 100 entries, shared across workspaces) |
+| `←` / `→`, `Home` / `End` | Move the cursor within the input; text is inserted/deleted at the cursor (CJK and emoji safe) |
+| `Ctrl+A` / `Ctrl+E` | Jump to start / end of input |
+| `Ctrl+W` / `Alt+Backspace` | Delete the word before the cursor |
+| `Ctrl+U` / `Ctrl+K` | Delete to start / to end of input |
+
+On resume (`-s <id>`, or the default latest session), the TUI replays the session's prior conversation on screen so you see where you left off. `shell_exec` output is shown inline by default (other tools' output needs `-v`). Tool lines show a short argument summary and duration, e.g. `⚙ file_read hello.txt 4ms`.
 
-On resume (`-s <id>`, or the default latest session), the TUI replays the session's prior conversation on screen so you see where you left off. `shell_exec` output is shown inline by default (other tools' output needs `-v`).
+**Multi-line paste**: pasting text with newlines (or >800 chars) collapses into a compact placeholder like `[#1 pasted 3 lines]` in the input; you can keep typing around it, and the original text is expanded back in full on submit. Pasted content is inserted at the cursor position.
 
 ## File, Image, and Scope References
 
@@ -174,10 +192,16 @@ Attach files or images to your message with `@file` and `@image`, or pull a dire
 ```
 packages/cli/
   src/
-    index.ts        — Entry: arg parsing, mode dispatch, SIGINT handling
+    index.ts        — Entry: subcommand dispatch (tui/cli/agents/sessions/server/setup/acp), SIGINT handling
     harness.ts      — Shared agent harness wrapping SessionManager
     cli.ts          — Non-interactive: stdin/args → agent → stdout → exit
-    tui.ts          — Interactive: readline loop + event display + commands
+    tui.tsx         — Interactive entry: mounts the ink app
+    tui/
+      app.tsx       — Root component: event reducer, blocks, submit/command handling
+      line-editor.ts — Grapheme-aware pure line-editing functions (cursor, insert, delete)
+      history.ts    — Persistent input history (~/.halo/global/tui-history.json)
+      components/   — input-box, text-input, messages, streaming, status-bar,
+                      slash-suggest, path-suggest, log-navigator, log-viewer, banner
     format-usage.ts — Usage-line formatter (mirrors admin UsageLine badge order)
     resolve-refs.ts — @file / @image reference resolution with size limits
     render-md.ts    — Terminal markdown rendering (marked + marked-terminal)

package/bundled-docs/guide/getting-started.md

@@ -6,8 +6,9 @@ What to do the first time you open Halo.
 
 Open `http://localhost:9527` (or your deployment URL) in a browser and enter the password.
 
-- The default password is printed to the **server console** (auto-generated if you haven't set `HALO_PASSWORD`)
-- You can also pin a password via `server.password` in `~/.halo/secrets/config.yaml`
+- Set the password during `halo setup` (interactive) — it's stored as a scrypt hash in `~/.halo/secrets/config.yaml`
+- Or supply it via the `HALO_PASSWORD` env var (handy for CI / Docker), which takes precedence over the stored hash
+- If neither is set, the server refuses to start (it prints `admin password not configured` and exits)
 
 ## Open a workspace
 

package/bundled-docs/requirements/editor.md

@@ -42,7 +42,7 @@ Non-text files go through `FilePreview`, which looks up a **plugin** in the prev
 - **PDF** — browser-native iframe
 - **DOCX / DOC** — `mammoth` → HTML (parsed in a Web Worker so the UI stays responsive)
 - **XLSX / XLS / CSV** — `xlsx` (SheetJS) → table (parsed in a Web Worker; CSV decoded as UTF-8 with BOM strip)
-- **PPTX / PPT** — `pptx-preview` list mode. Fidelity is approximate — complex animations / SmartArt / embedded fonts may not render perfectly; users can download for the exact source. Flagged `heavy: true` so only the *active* pptx mounts (canvas-based rendering needs the main thread)
+- **PPTX / PPT** — `pptx-preview` list mode. Fidelity is approximate — complex animations / SmartArt / embedded fonts may not render perfectly; users can download for the exact source. Flagged `heavy: true` so only the *active* pptx mounts (canvas-based rendering needs the main thread). **Speaker-notes sidebar**: notes are extracted from the pptx zip in presentation (play) order and listed on the left; clicking a note scrolls to the corresponding slide (a domIndex mapping bridges play order to pptx-preview's part-filename render order, so reordered decks still land on the right slide). Collapsible with the state remembered in localStorage (`halo.pptxNotesHidden`); the sidebar doesn't appear at all when no slide has notes. Decks with dangling `[Content_Types].xml` overrides (e.g. some WPS exports) are repaired before rendering; if zero slides render anyway, a real error UI is shown instead of a silent black wrapper
 - **Images / video / audio** — native `<img>` / `<video>` / `<audio>`, supports HTTP Range for seek-without-full-download
 
 All previews share a **standard header** (`PreviewShell`) with filename, Download, Open-as-Text, and an `extraToolbar` slot for plugin-specific buttons (e.g. DOCX Print, XLSX sheet tabs).

package/bundled-docs/requirements/explorer.md

@@ -12,6 +12,16 @@ VS Code-style file tree sidebar with multi-select, drag-drop, right-click menu.
 ### Path input
 - Explorer top bar has a path input + 📁🔍 picker button
 - Pressing Enter calls `GET /api/fs/exists?path=...` first — a miss shows an alert, no switch
+- **Recent-workspaces dropdown**: focusing the input shows the most-recently-used list; typing filters it by substring. Each row shows the folder name + full path; clicking one switches to it; a hover "×" removes a single entry. Entries are recorded only after a switch validates the path (so invalid paths never land), in canonical resolved form, MRU-ordered and deduped, capped at 8. Persisted in localStorage (`halo_recent_workspaces`)
+
+### Desktop windows (multi-window)
+Desktop app only — the browser has one tab per window natively.
+- **New window**: `Cmd+N` (macOS, via the File menu) / `Ctrl+N` (Windows/Linux, bound at the webContents level since those platforms have no app menu). Each window is a fresh view onto the **one shared local server** — no second server process spawns.
+- **Per-window workspace**: windows share the server origin, hence one localStorage, so a window tracks its own workspace via its URL `?folder=` (not localStorage, which would clobber across windows). Different windows can sit on different workspaces; the same workspace can be open in two windows.
+- **Quit semantics** (platform split): on macOS, closing every window keeps the app in the Dock (only `Cmd+Q` truly exits) and clicking the Dock icon reopens a window; on Windows/Linux there's no Dock to resummon from, so closing the last window quits.
+- **Pin (always-on-top)** acts per-window — each window pins independently.
+- **Activity awareness**: while the agent streams a reply the sidebar's workspace name carries an amber pulsing dot (emerald when idle) and the window title gains a `●` prefix (`● Halo — <name>` busy vs `Halo — <name>` idle) — both are plain web behaviour that Electron mirrors to the native title bar.
+- **Finish notification** (works in both the desktop app and a plain browser): an opt-in bell toggle sits in the activity bar next to the pin, **off by default**, persisted per-machine in localStorage (`halo_notify_on_finish`). It's shown whenever a notification can be raised — the desktop shell (`window.haloNotify` bridge) or a browser with the Web Notification API; turning it on in a browser requests Notification permission from within the toggle click (the required user gesture). When on, the busy→idle edge of the *same* still-open session triggers two decoupled cues: a **self-synthesized WebAudio chime** that always plays (regardless of focus — an audible "it's done" even while you're watching the tab, and not subject to the OS per-site notification-sound setting), plus — **only when the window is unfocused** — a banner (desktop: native notification + Dock bounce / taskbar flash; browser: a Web Notification whose click refocuses the tab). Focused → chime only, no banner.
 
 ### Directory picker (FolderPicker modal)
 Visual directory browser opened by the 📁🔍 button:
@@ -54,6 +64,7 @@ Items shown depend on the click target:
 |---|---|---|
 | New File / New Folder | Always | `POST /api/files/new` · `mkdir`; auto-expands the parent folder so the inline input is visible |
 | Open in Integrated Terminal | Always | Spawns a terminal at the target dir (or file's parent) |
+| Reveal in File Manager | Desktop app only | Opens the OS file manager (Finder / Explorer / Linux FM) at the target — a folder opens itself, a file is highlighted in its parent dir. Hidden in a plain browser (gated on the `window.haloReveal` IPC bridge exposed by the desktop preload) |
 | Open to the Side | File only | Splits the editor and opens the file in the right pane |
 | Download | File only | `GET /api/files/download?path=...` |
 | Rename | Single file/folder | `POST /api/files/rename` |