@turmind/halo 1.0.2 → 1.1.0

package/bundled-docs/dev/api.md

@@ -2,7 +2,7 @@
 
 All REST endpoints are served by Hono on port 9527 at `/api/`.
 
-Auth: most `/api/*` routes require a valid JWT cookie (`halo_token`). Exceptions in `PUBLIC_PATHS` (`middleware/auth.ts`) bypass the cookie: `/api/auth/*`, the web-channel routes (`/api/web/chat|stop|history|subscribe|file`), `/api/show/state|session`, and `/api/metrics` — these are unauthenticated or use a web-channel `x-token` instead.
+Auth: most `/api/*` routes require a valid JWT cookie (`halo_token`). Exceptions in `PUBLIC_PATHS` (`middleware/auth.ts`) bypass the cookie: `/api/auth/login|check|logout` (but **not** `/api/auth/change-password`), the web-channel routes (`/api/web/chat|stop|history|subscribe|file`), `/api/show/state|session`, and `/api/metrics` — these are unauthenticated or use a web-channel `x-token` instead.
 
 ## Health
 
@@ -17,8 +17,9 @@ File: `packages/server/src/middleware/auth.ts`
 | Method | Path | Purpose |
 |---|---|---|
 | POST | `/api/auth/login` | Password login, returns a JWT cookie |
-| POST | `/api/auth/logout` | Clears the auth cookie |
-| GET | `/api/auth/check` | Validates the current token; refreshes stale tokens |
+| POST | `/api/auth/logout` | Clears the auth cookie (Set-Cookie `Max-Age=0`). In `PUBLIC_PATHS`. No server-side token blacklist — a copied JWT stays valid until natural expiry |
+| GET | `/api/auth/check` | Validates the current token; refreshes stale tokens. Also returns `badge` (the `HALO_BADGE` env, `null` when unset) on both the 200 and the 401 so the login page can brand its favicon/title too |
+| POST | `/api/auth/change-password` | Change the admin password. **Not** in `PUBLIC_PATHS` — requires a valid JWT cookie. Persists the new scrypt hash to `~/.halo/secrets/config.yaml`; takes effect immediately (no restart), does **not** rotate `jwt_secret` so existing sessions stay signed in |
 
 ## Files
 
@@ -30,7 +31,6 @@ File: `packages/server/src/routes/files.ts`
 | GET | `/api/files/search?projectId=&q=[&limit=][&dirsOnly=1]` | Recursive name search. Default limit 200, max 1000. Scans up to 50000 entries then truncates; returns `{matches, truncated}`. `dirsOnly=1` matches directories instead of files (powers the chat `@scope` directory completion). |
 | GET | `/api/files?path=&projectId=` | Read file content (max 10 MB) |
 | GET | `/api/files/stat?path=&projectId=` | Lightweight mtime + size |
-| GET | `/api/files/diff?path=&projectId=` | Git diff |
 | GET | `/api/files/download?path=&projectId=&inline=` | Download or inline-preview — streams the file (no full read into memory), supports `Range` (206 Partial Content) so `<video>`/`<audio>` can seek + partial-load; aborts the read if the client disconnects |
 | PUT | `/api/files` | Save file (body: `{path, content, projectId}`) |
 | POST | `/api/files/new` | Create empty file |
@@ -39,7 +39,9 @@ File: `packages/server/src/routes/files.ts`
 | POST | `/api/files/upload` | Multipart upload |
 | DELETE | `/api/files?path=&projectId=` | Delete file or directory (recursive) |
 
-All file operations validate the path stays inside the project root (prevents path traversal). One exception: `GET /api/files/download` also accepts absolute paths under `/tmp/` so that agent-produced working files (e.g. Playwright screenshots) can be inline-previewed from chat media chips.
+**Inline Content-Type** for images comes from core's shared extension→MIME table (`imageMimeFromExt`, `packages/core/src/media/mime.ts`) on both `/api/files/download?inline=1` and `/api/web/file`; each route keeps only its own non-image entries (pdf / html / video / audio) and falls back to `application/octet-stream`. That table is why `.bmp` now serves as `image/bmp` on both — the two routes used to carry their own copies and `/api/web/file` returned `application/octet-stream` for it. `.svg` / `.ico` / `.avif` get a real image Content-Type when served, but are deliberately not "photos" (they're outside `IMAGE_EXTS`) so they never reach a vision model or a channel's sendPhoto.
+
+All file operations validate the path stays inside the project root (prevents path traversal). The check (`validatePath` in `routes/workspace-path.ts`, shared with `data-preview.ts` and `git.ts`) realpaths both sides — longest existing ancestor plus the re-appended tail — so a symlink inside the workspace pointing outside it is rejected too, not just lexical `../`. One exception: `GET /api/files/download` also accepts absolute paths under `/tmp/` so that agent-produced working files (e.g. Playwright screenshots) can be inline-previewed from chat media chips.
 
 ### Filesystem browse (not project-scoped — for the workspace picker)
 
@@ -48,9 +50,29 @@ All file operations validate the path stays inside the project root (prevents pa
 | GET | `/api/fs/home` | Returns server `homedir()` — fallback when the frontend has no `?folder=` URL param. Returns `{ home }`. |
 | GET | `/api/fs/exists?path=/abs` | Validates an absolute path exists and whether it's a directory. Returns `{exists, isDirectory?}`. |
 | GET | `/api/fs/browse?path=/abs` | Lists immediate directory children (hidden ones dropped). Returns `{path, parent, entries: [{name, path}]}`. |
-| POST | `/api/fs/workspace/resolve` | Resolve `{path}` to an absolute path and run `ensureWorkspaceHalo()`. Returns `{id, path}`. Used by the workspace-picker on switch. |
+| POST | `/api/fs/workspace/resolve` | Resolve `{path}` to an absolute path and run `ensureWorkspaceHalo()`. Returns `{id, path}`. Used by the workspace-picker on switch. 404 `path not found` when it doesn't exist; 400 `not a directory` for a file; 400 `filesystem root cannot be a workspace` for `/` (or a drive root) — `ensureWorkspaceHalo()` writes a whole `.halo/` scaffold, so those two shapes are refused before the write. Deeper system trees (`/usr`, `/etc`) are deliberately **not** banned. |
+
+Absolute paths only. Purpose: Explorer's workspace picker and switching validation. `/api/fs/browse` is intentionally unrestricted (it's a read-only picker over the server's filesystem — same trust boundary as the admin cookie). Reading/writing files still goes through `/api/files/*` and remains project-sandboxed.
+
+## Data Preview
+
+File: `packages/server/src/routes/data-preview.ts`
+
+Tabular file previews (Parquet / SQLite / CSV / TSV) for the Canvas editor — parsed server-side, returned as schema + one page of JSON-safe rows so large files never travel to the browser.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/data-preview/sqlite/tables?path=&projectId=` | List tables. Returns `{ tables: [{name, rowCount}] }` |
+| GET | `/api/data-preview/sqlite/rows?path=&projectId=&table=&offset=&limit=` | One page of rows. Returns `{ table, columns, rows, totalRows, offset, limit }` |
+| GET | `/api/data-preview/parquet?path=&projectId=&offset=&limit=` | Schema + one page of rows. Returns `{ columns, rows, totalRows, offset, limit }` |
+| GET | `/api/data-preview/csv?path=&projectId=&offset=&limit=` | Header + one page of data rows. Returns `{ columns, rows, totalRows, hasMore, offset, limit }` |
+
+Pagination: `limit` defaults to 100, capped at 1000. Same `(path, projectId)` resolution + traversal guard as `files.ts` (400/403/404 with a readable `{error}` body, never a 500 stack trace).
 
-Absolute paths only. Purpose: Explorer's workspace picker and switching validation. Reading/writing files still goes through `/api/files/*` and remains project-sandboxed.
+- **sqlite/tables**, **sqlite/rows** — opens the db `readonly` + `fileMustExist`, closed per request (no lingering lock on a live WAL db). Table names can't be parameterized, so they're gated on `sqlite_master` membership before being quoted into the query.
+- **parquet** — reads only the footer + the row groups covering the requested page (hyparquet), never the whole file.
+- **csv** — streaming RFC 4180 tokenizer, memory O(page). Delimiter is sniffed from the header line (`,` / `;` / tab, comma wins ties); `.tsv` forces tab. `totalRows` is a lazy lower bound while `hasMore` is true (exact once the scan reaches EOF, to avoid re-reading the whole file on every page turn). A single row over 1MB is rejected with 400 (delimiter-flood / non-CSV guard).
+- All four fold cells to JSON scalars: bigints beyond ±2^53 become exact strings, BLOB/binary becomes a `<blob N bytes>` placeholder, `Date` becomes ISO text.
 
 ## Session Logs (unified)
 
@@ -61,34 +83,42 @@ Unified session log API — list + read session files across all agents.
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/api/sessions/logs?projectId=` | List session metadata, keyset-paginated. Default returns each top-level row + all descendants (sidebar tree); `rootOnly=1` returns roots only (chat-header dropdown) |
-| GET | `/api/sessions/logs/:id?projectId=` | Full session log (scans across agent dirs) |
-| DELETE | `/api/sessions/logs/:id?projectId=` | Delete the session log |
-| PATCH | `/api/sessions/logs/:id?projectId=` | Rename a session (admin-only) — updates the log file's title. Accepts any session id (root or sub-agent); the sidebar exposes the rename affordance on every row |
+| GET | `/api/sessions/logs/:id?projectId=` | Full session log (scans across agent dirs) — the **active** file only; archived history is a separate call |
+| GET | `/api/sessions/logs/:id/archive/:n?projectId=` | One archived UI-log segment — see [detail](#get-apisessionslogsidarchivenprojectidabs) |
+| DELETE | `/api/sessions/logs/:id?projectId=` | Delete the session log (and all of its archive segments) |
+| PATCH | `/api/sessions/logs/:id?projectId=` | Rename a session (admin-only) — updates the log file's title and the mirrored `agent_sessions.title`. Accepts any session id (root or sub-agent); the sidebar exposes the rename affordance on every row |
 | GET | `/api/sessions/goal?projectId=` | Latest goal binding for the workspace (goal-mode banner / input-lock seed) — see [detail](#get-apisessionsgoalprojectidabs) |
 
-The list endpoint returns flat metadata (id / agentId / agentName / title / timestamps / messageCount / parentSessionId / stoppedAt / contextTokens / totalOutputTokens / goalSessionId). The frontend builds the tree from `parentSessionId`; `goalSessionId` (non-null on a goal-bound worker row) drives the 🎯 badge.
+The list endpoint returns flat metadata (id / agentId / agentName / title / timestamps / exchangeCount / parentSessionId / stoppedAt / contextTokens / totalOutputTokens / goalSessionId), served from the mirrored `agent_sessions` columns rather than by parsing each session file (rows predating the columns are backfilled from the file on first read). The frontend builds the tree from `parentSessionId`; `goalSessionId` (non-null on a goal-bound worker row) drives the 🎯 badge.
 
 The get endpoint returns the full session file. If only `rawMessages` is present (no event-log `messages`), `convertRawMessages()` transforms it into display format on the fly.
 
-### Legacy DB sessions
+## Channel accounts — shared field validation
 
-| Method | Path | Purpose |
+`workspacePath` and `accessLevel` are validated at the REST boundary on both
+POST and PATCH across all five channels (web / wechat / telegram / slack /
+feishu) — one shared pair of checks in `channels/shared/accounts.ts`, so the
+five can't drift (they did: four PATCHes never checked `isAbsolute`, and only
+wechat's PATCH rejected an unknown `accessLevel`):
+
+| Field | Rule | 400 body |
 |---|---|---|
-| GET | `/api/sessions?projectId=` | List sessions (DB, legacy) |
-| GET | `/api/sessions/:id` | Full session (DB, legacy) |
-| DELETE | `/api/sessions/:id` | Delete session (DB, legacy) |
+| `accessLevel` | Must be one of the channel's legal levels when present; absent = leave unchanged. **web** allows `full` / `workspace` / `readonly` / `observer` (halo-city / metrics tokens are minted here); the **four chat channels** allow only `full` / `workspace` / `readonly` — `observer` is a dashboard role, not a chat identity | `{error: "accessLevel must be one of: …"}` |
+| `workspacePath` | Absolute and existing. Empty string / relative path → 400; PATCH treats *absence* as "leave the binding alone" but validates any value supplied. On success `ensureWorkspaceHalo()` scaffolds `.halo/` | `{error: "workspacePath must be absolute"}` / `{error: "workspace path not found"}` |
+
+POST additionally rejects a missing `workspacePath` with `{error: "workspacePath required"}`. Stored levels are still normalized to `readonly` on read, but the db no longer holds a value no code path agrees with.
 
-## Weixin Channel
+## WeChat Channel
 
-File: `packages/server/src/routes/weixin.ts`
+File: `packages/server/src/routes/wechat.ts`
 
 | Method | Path | Purpose |
 |---|---|---|
-| POST | `/api/weixin/login/start` | Start the QR login flow, returns `{qrcodeUrl, sessionKey}` |
-| POST | `/api/weixin/login/wait` | Poll QR status. body: `{sessionKey, workspacePath, label?, language?}`; on success the account is inserted and long-polling starts |
-| GET | `/api/weixin/accounts` | List every bot account |
-| PATCH | `/api/weixin/accounts/:id` | Change label / workspacePath / enabled / accessLevel / language |
-| DELETE | `/api/weixin/accounts/:id` | Stop long-polling and delete the DB row |
+| POST | `/api/wechat/login/start` | Start the QR login flow, returns `{qrcodeUrl, sessionKey}` |
+| POST | `/api/wechat/login/wait` | Poll QR status. body: `{sessionKey, workspacePath, label?, accessLevel?, language?}`; on success the account is inserted and long-polling starts. `workspacePath` must be absolute — checked **before** the blocking QR wait so a typo is rejected without asking the user to scan; existence + `.halo/` scaffolding are only checked after the scan lands, so an abandoned login never scaffolds a directory |
+| GET | `/api/wechat/accounts` | List every bot account |
+| PATCH | `/api/wechat/accounts/:id` | Change label / workspacePath / enabled / accessLevel / language |
+| DELETE | `/api/wechat/accounts/:id` | Stop long-polling and delete the DB row |
 
 See [design/wechat.md](../design/wechat.md).
 
@@ -103,7 +133,7 @@ File: `packages/server/src/routes/telegram.ts`. Admin cookie auth. Mounted under
 | PATCH | `/api/telegram/accounts/:id` | Update `label` / `workspacePath` / `enabled` / `accessLevel` / `allowedUsers` / `language`. Stops then restarts the bot if still enabled |
 | DELETE | `/api/telegram/accounts/:id` | Stop long-poll and delete the row |
 
-`workspacePath` must be absolute and exist; `ensureWorkspaceHalo()` runs on POST/PATCH.
+`workspacePath` / `accessLevel` follow the [shared validation rules](#channel-accounts--shared-field-validation).
 
 ## Slack Channel
 
@@ -139,7 +169,7 @@ File: `packages/server/src/routes/cron.ts`. Admin cookie auth. REST CRUD over `c
 |---|---|---|
 | GET | `/api/cron/jobs?limit=&before=` | Cursor-paginated newest-first by `createdAt`. Default `limit` 20, max 100; `before` is a `createdAt` cursor. Returns `{jobs, hasMore, nextCursor}`. Each job has `targets` decoded and a live `nextRunAt` (computed from schedule/runAt) |
 | POST | `/api/cron/jobs` | Create a job. Body: `{label?, workspacePath, agentId, userPrompt, schedule, runAt?, timezone?, targets?, enabled?}`. Exactly one of `schedule` (5-field cron) or `runAt` (epoch ms, future) is required; mutually exclusive. Returns `{ok, id}` |
-| PUT | `/api/cron/jobs/:id` | Partial update over the same fields. Re-validates `schedule` / `runAt`; flips schedule/unschedule on `enabled`. Returns `{ok}` |
+| PUT | `/api/cron/jobs/:id` | Partial update over the same fields. Re-validates `schedule` / `runAt` and enforces trigger-mode exclusivity on the **merged** row: both in one body → 400 `schedule and runAt are mutually exclusive`; supplying one side is a mode switch that implicitly clears the other; a body that clears the active side without supplying a replacement → 400 `schedule or runAt required`. `runAt` must be a finite future epoch-ms number or `null`. Flips schedule/unschedule on `enabled`. Returns `{ok}` |
 | DELETE | `/api/cron/jobs/:id` | Unschedule, delete every `cron_runs` row for the job, then delete the job. Returns `{ok}` |
 | POST | `/api/cron/jobs/:id/run-now` | Fire the job immediately (fire-and-forget). Returns `{ok}` |
 | POST | `/api/cron/reload` | Re-read every job from db and rebuild schedules. Returns `{ok}` |
@@ -162,14 +192,14 @@ File: `packages/server/src/routes/cron.ts`. Admin cookie auth. REST CRUD over `c
 
 ## Source Control (Git)
 
-File: `packages/server/src/routes/git.ts`. Admin cookie auth. Backs the Source Control panel + Explorer git decorations. All project-scoped reads take `projectId=<absPath>`; writes take it in the JSON body. A write (stage/unstage/commit/push/pull/init/remote) broadcasts `file:changed` (path `.git`) so the panel, graph and explorer decorations auto-refresh without polling — the file watcher ignores `.git`, so the route re-broadcasts it itself. Path params on diff are traversal-checked against the project root.
+File: `packages/server/src/routes/git.ts`. Admin cookie auth. Backs the Source Control panel + Explorer git decorations. All project-scoped reads take `projectId=<absPath>`; writes take it in the JSON body. A write (stage/unstage/commit/push/pull/init/remote) broadcasts `file:changed` (path `.git`) so the panel, graph and explorer decorations auto-refresh without polling — the file watcher ignores `.git`, so the route re-broadcasts it itself. The broadcast is **workspace-scoped** (`broadcastToWorkspace`): only clients bound to that workspace get it, so a git write in A no longer makes every tab showing B refetch status + ignored + log. Path params on diff are traversal-checked against the project root.
 
 ### Repo state (read)
 
 | Method | Path | Purpose |
 |---|---|---|
 | GET | `/api/git/status?projectId=` | Structured working-tree status. A folder that isn't a git work-tree **root** (no repo, or merely nested inside an ancestor's repo) returns `{isRepo: false}` (200, not 500) so the panel shows its initialize/empty state. Otherwise `{isRepo: true, branch, tracking, ahead, behind, files: [{path, index, workingDir, from?}]}` — `index`/`workingDir` are the two porcelain status chars (X staged / Y working) |
-| GET | `/api/git/ignored?projectId=` | `.gitignore`'d paths for graying out in the explorer; ignored directories are collapsed to a single entry (e.g. `node_modules`) rather than expanded. Returns `{ignored: string[]}`. Runs with `core.quotepath=false` so non-ASCII (e.g. Chinese) paths come back literal, not octal-escaped — the frontend prefix-matches them against tree node paths |
+| GET | `/api/git/ignored?projectId=` | `.gitignore`'d paths for graying out in the explorer; ignored directories are collapsed to a single entry (e.g. `node_modules`) rather than expanded. Returns `{ignored: string[]}` (`{isRepo:false, ignored:[]}` when the folder isn't a work-tree root — same guard as `status`, applied to all six read endpoints so a workspace nested inside an ancestor's repo never leaks its state). Runs with `core.quotepath=false` so non-ASCII (e.g. Chinese) paths come back literal, not octal-escaped — the frontend prefix-matches them against tree node paths |
 | GET | `/api/git/diff?projectId=&path=[&staged=0\|1][&from=][&commit=]` | Two sides for the Monaco diff editor. With `commit`, shows that commit's own change (parent vs commit); without it, the working-tree (or `staged=1`) diff. `from` carries the old path on a rename. Returns `{path, original, modified, ...}`. 400 if `path` missing, 403 on traversal |
 | GET | `/api/git/log?projectId=[&limit=50]` | Recent commits for the graph. `limit` default 50, capped at 2000. Returns `{commits: [{hash, shortHash, message, author, date, refs, pushed}]}` — `pushed: boolean` marks whether the commit is on a remote (graph dims pushed nodes gray, paints local-only ones blue). No-upstream branches compute it via `rev-list HEAD --not --remotes`, not `rev-list HEAD` |
 | GET | `/api/git/commit-files?projectId=&hash=` | Files changed by one commit. Returns `{files: [{path, status, from?}]}` (`status` = M/A/D/R/C; `from` set on rename/copy). 400 if `hash` missing |
@@ -177,6 +207,8 @@ File: `packages/server/src/routes/git.ts`. Admin cookie auth. Backs the Source C
 
 ### Mutations (write — each broadcasts `file:changed`)
 
+Every write except `/api/git/init` is gated on the project being a git work-tree **root** (`getGitForWrite` → `isRepoRoot()`): a folder that's merely nested inside an ancestor's repo gets **409** `{error: 'Not a git repository root'}` instead of silently mutating the ancestor. Reads keep their 200-with-empty-payload shape for the same state. `/api/git/init` is deliberately ungated — initializing a nested folder's own repo is exactly its purpose.
+
 | Method | Path | Purpose |
 |---|---|---|
 | POST | `/api/git/stage` | Body `{projectId, paths: string[]}`. `git add`. 400 if `paths` empty |
@@ -217,6 +249,21 @@ File: `packages/server/src/routes/web.ts`
 
 ### Public endpoints (token auth via `x-token` header or `?token=` query)
 
+Token auth for the whole public surface — these routes, halo-city's
+`/api/show/*`, and `/api/metrics` — runs through one shared core,
+`resolveTokenAuth` in `middleware/web-token.ts`: header/query token parsing,
+account lookup (must exist **and** be enabled), and the per-IP brute-force
+bookkeeping in one place (5 strikes / 15 min lockout, one `web-token` bucket
+shared by the three surfaces, independent of admin-login lockouts). A missing
+token is a plain 401 and **not** a strike; only an invalid one counts.
+
+Statuses are identical everywhere (`locked_out` 429, `missing_token` /
+`invalid_token` 401) — only the **body shape** differs, which is why each surface
+maps the failure itself: web + `/api/show/*` share the JSON renderer
+(`{error: "token required" | "invalid token" | "too many failed attempts, try again later"}`),
+`/api/metrics` answers in Prometheus comment lines (`# …`) so a scraper never
+gets JSON, and additionally gates on `accessLevel`.
+
 | Method | Path | Purpose |
 |---|---|---|
 | POST | `/api/web/chat` | Send message, receive SSE stream. Body: `{message, images?, workspace?, sessionId?, agentId?}` (overrides also accepted as `?workspace=`/`?sessionId=` query or `x-workspace`/`x-session-id` headers; `workspace` only honored when token has `accessLevel: full`) |
@@ -229,8 +276,9 @@ See [design/web.md](../design/web.md).
 
 ## Show (world snapshot)
 
-File: `packages/server/src/routes/show.ts`. Token auth (same `x-token` as the
-Web channel; shares its brute-force lockout bucket). Read-only, cross-workspace
+File: `packages/server/src/routes/halo-city.ts`. Token auth (same `x-token` as
+the Web channel — same shared `resolveTokenAuth` core, same JSON error shape,
+same brute-force lockout bucket). Read-only, cross-workspace
 snapshot powering the `halo-city` pixel visualizer — one call returns the whole
 runtime so the frontend can render rooms (workspaces) + characters (sessions).
 
@@ -241,7 +289,7 @@ runtime so the frontend can render rooms (workspaces) + characters (sessions).
 
 `observer` is more than an aggregate-counts role: past `/show/state`, it can also call `/show/session` to read **any workspace's** session transcript (last 40 messages, content truncated to 600 chars, tool input to 200 chars). Mint it knowing it grants cross-workspace transcript read access, not just dashboard counters.
 
-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.
+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 }`. `messageCount` here is the session file's raw UI-log length (an activity signal for the citizen animation) — deliberately **not** the admin list's lifetime `exchangeCount`; it shrinks when a compact archives history. `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).
 
@@ -268,6 +316,8 @@ File: `packages/server/src/routes/agent-configs.ts`
 | DELETE | `/api/agent-configs/:id/sessions/:sessionId` | Delete a session |
 | DELETE | `/api/agent-configs/:id/sessions?all=1` | Delete every session for the agent |
 
+Every `:id` / `:sessionId` route param that becomes a path segment (here and in `DELETE /api/skills/:id`) is validated with `isSafeIdSegment()` (`routes/workspace-path.ts`) before it reaches `path.join` — `.` / `..` rejected outright, everything else must match `/^[\w.:>\u4e00-\u9fff-]+$/` (the union of the real id charsets: slug + CJK agent names, `__internal__`, and session ids embedding `_ - : . >`). Hono decodes `%2F` / `%2e` into params, so a raw `..%2F..%2Fetc` would otherwise arrive as a traversal. A rejected param is **400** (`Invalid agent id` / `Invalid skill id` / `Invalid session id`), distinct from the **404** a well-formed-but-missing session file gets.
+
 ## Skills
 
 File: `packages/server/src/routes/skills.ts`
@@ -300,6 +350,8 @@ File: `packages/server/src/routes/settings.ts`
 | PATCH | `/api/settings` | Update a single key |
 | DELETE | `/api/settings` | Delete a key |
 
+PATCH / DELETE walk the dotted key layer by layer, so a segment of `__proto__` / `constructor` / `prototype` is rejected with 400 `Invalid key` — the leaf assignment would otherwise land on `Object.prototype` and pollute every object in the process.
+
 ## Metrics
 
 File: `packages/server/src/routes/metrics.ts`.
@@ -308,7 +360,7 @@ File: `packages/server/src/routes/metrics.ts`.
 |---|---|---|
 | GET | `/api/metrics` | Prometheus text exposition (gauges) of deployment-wide runtime: `halo_uptime_seconds`, `halo_workspaces`, `halo_sessions{status=}`, `halo_sessions_total`, `halo_context_tokens`, `halo_output_tokens` |
 
-In `PUBLIC_PATHS` (no admin cookie). Auth is a web-channel `x-token` (header or `?token=`) with a **global** scope — `full` or `observer` (the read-only role minted for dashboards/scrapes); a workspace-scoped token gets 403. Session counts come from each workspace's `listSessions`; token sums read the in-memory UIState of sessions this process actively drives.
+In `PUBLIC_PATHS` (no admin cookie). Auth is a web-channel `x-token` (header or `?token=`) resolved through the shared `resolveTokenAuth` core, but rendered as Prometheus comment lines instead of JSON — and it additionally requires a **global** scope: `full` or `observer` (the read-only role minted for dashboards/scrapes); a workspace-scoped token gets `# global-scope token (full or observer) required` with 403. Session counts come from each workspace's `listSessions`; token sums read the in-memory UIState of sessions this process actively drives.
 
 ## Self-Evolution
 
@@ -354,10 +406,36 @@ Source: [packages/server/src/middleware/auth.ts:123-134](../../../packages/serve
 
 ```json
 // 200 authenticated
-{ "authenticated": true }
+{ "authenticated": true, "badge": "DEV" }
 
 // 401 not authenticated
-{ "authenticated": false }
+{ "authenticated": false, "badge": "DEV" }
+```
+
+`badge` echoes the `HALO_BADGE` env (trimmed; `null` when unset) on **both**
+branches — this is the admin's first request, login page included, so the tab
+can brand its favicon + title from the very first paint without a second
+endpoint or a poll. Corollary: the value is readable **without authenticating**,
+so it must stay a label, not a secret. See [env.md](./env.md).
+
+### POST `/api/auth/change-password`
+
+Source: [packages/server/src/middleware/auth.ts](../../../packages/server/src/middleware/auth.ts). Admin-cookie authed (not in `PUBLIC_PATHS`). Validation order: wrong current password → 401; strength (≥8 chars, at least one letter and one digit) → 400 with the specific reason; new === old → 400. When `HALO_PASSWORD` env is set it overrides the stored hash at login, so a file rewrite would silently not take effect — the endpoint rejects with 400 instead.
+
+```json
+// Request
+{ "oldPassword": "...", "newPassword": "..." }
+
+// 200 OK — new scrypt hash persisted to ~/.halo/secrets/config.yaml,
+// live for the next login without restart; jwt_secret is NOT rotated
+// (existing cookies stay valid)
+{ "ok": true }
+
+// 401 wrong current password
+{ "error": "Incorrect current password" }
+
+// 400 strength / same-as-old / env-managed (message names the reason)
+{ "error": "Password must be at least 8 characters" }
 ```
 
 ### GET `/api/files/tree?projectId=<absPath>&path=<relPath>`
@@ -496,7 +574,7 @@ Two shapes, selected by `rootOnly`:
       "source": "explorer",
       "createdAt": "2026-04-30T08:00:00Z",
       "updatedAt": "2026-04-30T08:05:00Z",
-      "messageCount": 12,
+      "exchangeCount": 12,
       "parentSessionId": null,
       "contextTokens": 5975,
       "totalOutputTokens": 6058,
@@ -510,9 +588,11 @@ Two shapes, selected by `rootOnly`:
 
 Archived sessions are excluded by default; pass `?includeArchived=1` to include them.
 
+Rows are served from the mirrored `agent_sessions` metadata columns (`title` / `exchange_count` / `context_tokens` / `total_output_tokens`) — no session file is opened. A row whose `exchangeCount` is `null` predates those columns: the route reads that one file once, mirrors the values back, and never pays the cost again. `exchangeCount` counts **main user turns over the session's lifetime** (kept + archived), so unlike the file's `messageCount` it doesn't shrink when a compact archives history.
+
 ### GET `/api/sessions/logs/:id?projectId=<abs>`
 
-Returns the full session file. If only `rawMessages` is present (sub-agent sessions from SessionManager), `convertRawMessages()` transforms them into the display `messages` array on the fly.
+Returns the full session file — the **active** log only. Older exchanges that archiving moved out are fetched per-segment via [the archive endpoint](#get-apisessionslogsidarchivenprojectidabs). If only `rawMessages` is present (sub-agent sessions from SessionManager), `convertRawMessages()` transforms them into the display `messages` array on the fly.
 
 ```json
 // 200 — same shape as the on-disk JSON
@@ -527,11 +607,38 @@ Returns the full session file. If only `rawMessages` is present (sub-agent sessi
   "messageCount": 12,
   "contextTokens": 5975,
   "totalOutputTokens": 6058,
+  "archiveCount": 2,
   "messages": [ /* SessionMessage[] — see design/storage.md */ ],
   "rawMessages": [ /* optional */ ]
 }
 ```
 
+`messageCount` here is the **file's own** field (`messages.length`, shrinks on archive) — not the list endpoint's lifetime `exchangeCount`.
+
+### GET `/api/sessions/logs/:id/archive/:n?projectId=<abs>`
+
+Source: `packages/server/src/routes/session-archive.ts`
+
+One archived UI-log segment, gunzipped server-side. `n` counts up from 1; the client gets its anchor from `archiveCount` on the `state:snapshot` of subscribe/reattach ([ws.md](../design/ws.md)) and walks **down** from it. Segments are immutable once committed, so a client caches what it pulled and never re-requests. Admin-cookie gated (not in `PUBLIC_PATHS`).
+
+```json
+// 200
+{ "messages": [ /* SessionMessage[] — oldest-first within the segment */ ] }
+```
+
+Failure modes, in the order checked:
+
+| Status | Body | When |
+|---|---|---|
+| 500 | `session manager not initialized` | server not fully booted |
+| 400 | `projectId required` | missing query param |
+| 400 | `Invalid session id` | `id` fails `isSafeIdSegment` (path-traversal guard) |
+| 400 | `Invalid segment number` | `n` not a positive integer |
+| 404 | `Session not found` | no such session in this workspace |
+| 404 | `Segment not found` | `n > archiveCount` (uncommitted / nonexistent), or the segment file can't be read |
+
+The `n > archiveCount` check is the point, not a formality: `archiveCount` in the active file is the archive write's commit marker, so a segment file beyond it exists only because a crash interrupted the two-step write and must never be served. See [design/session.md](../design/session.md#ui-log-archiving).
+
 ### GET `/api/sessions/goal?projectId=<abs>`
 
 Source: `packages/server/src/routes/sessions.ts` (`findLatestGoal` in `agents/goal-mode.ts`)
@@ -608,9 +715,9 @@ Resolves declared schema (from `models/<id>.yaml` `secrets:` and `skills/<id>/co
 
 PUT replaces the full scope; DELETE takes `{scope, projectId, key}` and removes the key. The Settings page uses DELETE for both Reset (current scope removed → falls back to lower scope / unset) and orphan Remove.
 
-### POST `/api/weixin/login/start`
+### POST `/api/wechat/login/start`
 
-Source: [packages/server/src/routes/weixin.ts:42-46](../../../packages/server/src/routes/weixin.ts#L42-L46)
+Source: [packages/server/src/routes/wechat.ts:39-43](../../../packages/server/src/routes/wechat.ts#L39-L43)
 
 ```json
 // Request
@@ -620,7 +727,7 @@ Source: [packages/server/src/routes/weixin.ts:42-46](../../../packages/server/sr
 { "qrcodeUrl": "https://...", "sessionKey": "abc123" }
 ```
 
-### POST `/api/weixin/login/wait`
+### POST `/api/wechat/login/wait`
 
 ```json
 // Request
@@ -683,6 +790,18 @@ Attach this connection to a session's event stream. Sent on initial connect and
 }
 ```
 
+Idempotent per connection: re-subscribing to the same session releases this connection's previous listener and registers exactly one new one — safe to repeat. The client must also re-send it on receiving `listener:released` (see below).
+
+### `listener:released` (S→C)
+
+The server reclaimed this connection's event listener — sent when the connection was silent for >3 min (no inbound frames; e.g. a frozen tab whose network stack still answers protocol pings) or found CLOSED with a listener attached. The socket stays open; only the event stream is detached.
+
+```json
+{ "type": "listener:released", "sessionId": "sid_abc" }
+```
+
+On receipt the client re-sends `subscribe` to reattach — this frame is the only recovery signal a frozen-and-resumed tab gets, because the server's `__pong__` replies keep the client's own staleness detection from ever firing. Any WS consumer must send `__ping__` periodically (any inbound frame counts) or it will be reclaimed. See [design/ws.md](../design/ws.md#abandoned-listener-reclaim-and-the-__ping__-contract).
+
 ### `session:clear` (C→S)
 
 Detach from the current session (for `/session new`). Server unsubscribes the event listener without deleting the session.
@@ -712,5 +831,6 @@ Hard delete (JSON + SQLite rows, cascades to descendants) goes through the REST
 | `complete` | `stopReason`, `taskId?` | Turn finished |
 | `error` | `error` | Error message |
 | `chat:queued` | `reason`, `message` | Message queued (compact/busy) |
+| `listener:released` | `sessionId` | Event listener reclaimed — re-send `subscribe` (see above) |
 
 Events with `taskId` set belong to sub-agent turns (nested sessions); events without are the root agent's. Full list in [design/ws.md](../design/ws.md).

package/bundled-docs/dev/deploy.md

@@ -96,6 +96,54 @@ sudo systemctl daemon-reload
 sudo systemctl enable --now halo
 ```
 
+### Crash semantics — why `Restart=on-failure` is load-bearing
+
+The server **exits 1 on any uncaught exception** (`process.on('uncaughtException')`
+logs the stack, then `exit(1)` after a 100ms drain for queued stdout/WS frames).
+It does not try to keep serving: past an unwound handler the process may hold
+half-taken locks and half-written files, and since the db is the source of truth
+— every daemon (cron / evo ticker / channels) reconciles from it on boot — a
+restart is a full recovery while a zombie process silently corrupts state.
+
+So the supervisor is what turns a crash into a ~5s blip: the unit above pairs
+`Restart=on-failure` (fires exactly on non-zero exit) with `RestartSec=5`.
+Docker deployments want an equivalent `restart:` policy. Under a bare `nohup
+node dist/index.js` / foreground `halo server start` there is still no
+supervisor — a crash is a hard stop, with the stack in
+`~/.halo/global/logs/server.log` for whoever restarts it.
+`unhandledRejection` is only logged, not fatal.
+
+**`halo server start -d` brings its own bounded supervisor.** The detached
+process `-d` spawns is not the server: it re-execs `halo server start`
+(foreground) with `HALO_SUPERVISE=1`, and *that* process supervises the real
+server as its child (`packages/cli/src/server-supervisor.ts`). Policy:
+
+- **Restarts only on failure** — non-zero exit, or death by any signal other
+  than `SIGTERM` / `SIGINT`. `SIGKILL` (OOM killer) and `SIGSEGV` count as
+  crashes and *are* restarted; the same split systemd's `Restart=on-failure`
+  makes. A clean `exit(0)` is never restarted.
+- **Bounded**: at most **5 restarts per 5-minute sliding window**, then it gives
+  up (exit 1) with a log line telling you to fix the cause and re-run `halo
+  server start -d`.
+- **2s pause between attempts**, so an instant-crash loop can't spin the CPU.
+- Every decision lands in the daemon log as `[respawn] …`, on the same fds the
+  server writes to (`~/.halo/global/logs/server.log`).
+
+`halo server stop` (and `--force`) is not mistaken for a crash: it stamps the
+server pid into a marker file `~/.halo/global/server.stop` *before* signalling,
+and the supervisor stands down when it sees a marker naming the pid it just
+lost. Signals alone couldn't carry that intent (on Windows a `SIGTERM` surfaces
+as a plain `code 1`), and the marker is also what stops a respawn when `stop`
+arrives while the supervisor is mid-backoff. Stamping the pid rather than a bare
+flag keeps `restart` unambiguous — the new supervisor can't consume the outgoing
+one's marker.
+
+Pid ownership is unchanged: `~/.halo/global/server.lock` is still written and
+flock'd by the **server** process itself, so `halo server stop|restart|status`
+keep targeting the server exactly as before. The supervisor has no pidfile of
+its own; killing it directly leaves the server running as an orphan (same end
+state as the pre-supervisor `-d`), and `halo server stop` still stops it.
+
 ## 6. Verify
 
 ```bash

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

@@ -192,13 +192,13 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
    explicitly. This is what carries the built-in skills (incl. `send-file`),
    agents, prompts, models into the dmg.
 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);
+   --target=$NODE_VERSION_BARE` **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.
-6. **Download + stage node** — fetch `node-v22.11.0-<platform>-<arch>` from
+6. **Download + stage node** — fetch `node-$NODE_VERSION-<platform>-<arch>` from
    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.
@@ -236,7 +236,8 @@ 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
+- **better-sqlite3's ABI must match the BUNDLED node (`NODE_VERSION` in
+  `stage-runtime.mjs`, currently v22.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
@@ -245,9 +246,10 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   (`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.
+  1. `fetchTargetArchNatives()` runs `prebuild-install
+     --target=$NODE_VERSION_BARE` 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
@@ -257,6 +259,12 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   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.
+  **Bumping the bundled node = editing `NODE_VERSION` only.** Every effective
+  use (both `prebuild-install --target=` call sites, the host-major gate, the
+  download URL, the log lines) derives from it via `NODE_VERSION_BARE =
+  NODE_VERSION.slice(1)`. The version used to be re-typed as a literal
+  `22.11.0` in the `--target` args, so a bump silently left the ABI pinned to
+  the old node.
 
 - **Desktop port is sequential from 9527 (NOT random), and that's load-bearing
   for persistence.** `main.cjs` `findFreePort()` tries 9527 first, then scans
@@ -284,6 +292,32 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   have run the menu action that installs `/usr/local/bin/halo`; a fresh
   install that never did has no `halo` on any PATH.
 
+- **The installed `halo` launcher hard-codes paths inside the .app, so moving
+  the app breaks it — the script probes at run time.** `/usr/local/bin/halo` is
+  a tiny `sh` script (not a symlink: it must pair the bundled `node` with the
+  `cli-runtime` entry, which one symlink can't express), so its inlined
+  `Contents/Resources/...` paths go stale the moment the user drags the app
+  Downloads → /Applications — the classic post-install move. `buildCliLauncher()`
+  in `main.cjs` therefore emits a script that checks `-x $NODE` / `-f $CLI`
+  first and, when stale, retries at the standard location
+  (`/Applications/<AppName>.app/Contents/Resources/{node,cli-runtime/dist/index.js}`,
+  derived from the *current* bundle's basename). Still missing → print
+  "re-run Install 'halo' Command from the app menu" and `exit 127`, instead of
+  exec's cryptic "no such file or directory". Dev (`!app.isPackaged`) keeps the
+  plain one-line exec — `nodeBin` there may be a bare PATH lookup and
+  `resourcesPath` points into electron/dist, so there's no .app to heal against.
+
+- **First-run detection parses `secrets/config.yaml` with a real yaml parser.**
+  `configHasPassword()` used to regex `^\s*password:\s*\n\s*value:\s*"([^"]*)"`,
+  which only matched a *double-quoted* value. `halo setup` / change-password
+  write through the yaml Document API, which emits the scrypt hash unquoted (or
+  escape-folded across lines) depending on the prior scalar style — so a real
+  password regexed as "not set" and the desktop re-showed first-run setup on
+  every launch. It now `require()`s the `yaml` package out of the staged
+  server-runtime (always present — the desktop can't boot without it) and reads
+  `server.password.value`; the regex survives only as a `catch` fallback,
+  widened to accept unquoted scalars.
+
 - **Server child lifecycle.** On `before-quit` the main process sends SIGTERM,
   then force-SIGKILLs after 1.5 s. This is the backstop for a wedged server
   whose main thread is stuck in a syscall and never delivers SIGTERM. Without

package/bundled-docs/dev/env.md

@@ -111,6 +111,7 @@ Source: `packages/server/src/config.ts`
 | `HALO_LOG_MAX_FILES` | `5` | `config.yaml logging.max_files` | Retained rotated logs |
 | `HALO_LOG_LEVEL` | `warn` | `settings.yaml general.logging.level` | Log level: debug \| info \| warn \| error |
 | `HALO_JWT_SECRET` | (none) | `config.yaml server.jwt_secret` | JWT signing secret (generated by `halo setup` if missing; stripped from child-process env) |
+| `HALO_BADGE` | (none) | — | Environment badge (e.g. `DEV`) returned by `GET /api/auth/check` on **both** the 200 and 401 branches, so the admin can brand the login screen too. The admin repaints the favicon with a badge band and prefixes the tab title, making parallel dev/prod tabs tellable apart. dev and prod serve the same static build, so this has to be a runtime signal. Unset / whitespace-only → `null` → stock branding. Because the 401 branch carries it, the value is **public to unauthenticated clients** — keep it a label (`DEV`, `staging`), never anything sensitive. |
 | `HALO_RUNTIME_MODE` | (none) | — | `agentcore` runs the server as an Amazon Bedrock AgentCore Runtime container (see [design/agentcore.md](../design/agentcore.md)) |
 | `HALO_WORKSPACE` | `process.cwd()` | — | Workspace root in agentcore mode |
 
@@ -156,6 +157,8 @@ 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. 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.
 
+Once logged in, the password can also be changed from the panel (**Settings → Security**, requires the current password) — except when `HALO_PASSWORD` env manages it, in which case the endpoint refuses (the env value would keep winning at login).
+
 ## Verify
 
 ```bash