@turmind/halo 1.0.3 → 1.1.1

package/bundled-docs/dev/api.md

@@ -4,6 +4,8 @@ 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/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.
 
+Compression: every response negotiates gzip/deflate via `hono/compress` (`threshold: 1024` — bodies under 1 KiB pass through uncompressed), mounted after CORS so it covers both `/api/*` JSON and the served admin static assets. `text/event-stream` (SSE) is excluded, so `/api/web/chat`'s streamed reply is unaffected; WS upgrades never enter the Hono fetch pipeline either.
+
 ## Health
 
 | Method | Path | Purpose |
@@ -18,7 +20,7 @@ File: `packages/server/src/middleware/auth.ts`
 |---|---|---|
 | POST | `/api/auth/login` | Password login, returns a JWT cookie |
 | 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 |
+| 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
@@ -31,7 +33,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 |
@@ -40,7 +41,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)
 
@@ -49,9 +52,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)
 
@@ -62,34 +85,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"}` |
 
-## Weixin Channel
+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.
 
-File: `packages/server/src/routes/weixin.ts`
+## WeChat Channel
+
+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).
 
@@ -104,7 +135,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
 
@@ -140,7 +171,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}` |
@@ -163,7 +194,7 @@ 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)
 
@@ -178,6 +209,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 |
@@ -218,6 +251,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`) |
@@ -230,8 +278,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).
 
@@ -242,7 +291,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).
 
@@ -269,6 +318,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`
@@ -301,6 +352,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`.
@@ -309,7 +362,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
 
@@ -355,12 +408,18 @@ 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.
@@ -517,7 +576,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,
@@ -531,9 +590,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
@@ -548,11 +609,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`)
@@ -629,9 +717,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
@@ -641,7 +729,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

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 |
 

package/bundled-docs/dev/previews.md

@@ -15,6 +15,10 @@ previews/
 ├── ui/
 │   ├── preview-shell.tsx     Standard header (filename + Open-as-Text + Download + extraToolbar)
 │   ├── use-preview-fetch.ts  Hook: fetch + AbortController + parse, returns {data, error, loading}
+│   ├── use-data-fetch.ts     JSON-endpoint sibling: abortable fetcher → {data, error, loading},
+│   │                         for previews that parse server-side instead of raw bytes
+│   ├── data-table.tsx        Shared table renderer (headers + rows + prev/next pager) for
+│   │                         server-parsed previews (parquet / sqlite / csv)
 │   └── print.ts              Pop-up print helper
 ├── workers/                  Parse workers (one per heavy format)
 │   ├── worker-client.ts      Generic WorkerClient<T> class — id-routed postMessage
@@ -30,7 +34,10 @@ previews/
     ├── 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
+    ├── media.tsx / media-view.tsx
+    ├── parquet.tsx / parquet-view.tsx   Server-parsed: GET /api/data-preview/parquet
+    ├── sqlite.tsx / sqlite-view.tsx     Server-parsed: GET /api/data-preview/sqlite/*
+    └── csv.tsx / csv-view.tsx           Server-parsed: GET /api/data-preview/csv (csv + tsv)
 ```
 
 **Two-file-per-plugin pattern**: `foo.tsx` is tiny metadata (no runtime deps). `foo-view.tsx` holds the component and its heavy dependencies. The metadata file uses `React.lazy()` so the view file (and its deps) only loads when a user actually opens that file type.
@@ -40,7 +47,7 @@ previews/
 ```typescript
 interface PreviewPlugin {
   id: string                    // stable id, e.g. 'pdf'
-  extensions: readonly string[] // lowercase, no dot — e.g. ['xlsx', 'xls', 'csv']
+  extensions: readonly string[] // lowercase, no dot — e.g. ['xlsx', 'xls'] (csv/tsv is a separate plugin)
   Component: React.ComponentType<PreviewProps>
   heavy?: boolean               // true = main-thread-heavy; active-only mount, skip MRU cache
 }
@@ -48,6 +55,8 @@ interface PreviewPlugin {
 interface PreviewProps {
   name: string         // full filename including extension
   path: string         // relative workspace path (or absolute for /tmp files)
+  projectId?: string   // workspace absolute path — needed by server-parsed plugins
+                        // (parquet/sqlite/csv) to call /api/data-preview/*
   viewUrl: string      // for inline viewing, supports HTTP Range
   downloadUrl: string  // for forced download (used by the shell's Download button)
   onOpenAsText?: () => void  // set when the file can also be force-opened as text
@@ -206,13 +215,59 @@ Only pptx currently uses this. Don't set it by default — the MRU cache gives m
 
 When the user right-clicks a previewable file in Explorer and picks "Open as Text", Canvas closes the preview tab and opens the raw file in Monaco. The preview plugin receives this as `props.onOpenAsText` — pass it straight through to `PreviewShell` and the button appears automatically.
 
+## Two plugin patterns: raw-bytes vs. server-parsed
+
+Most built-in plugins (pdf, docx, xlsx, pptx, media) are **raw-bytes**: `usePreviewFetch` downloads the whole file as an ArrayBuffer via `GET /api/files/download?inline=1`, then parsing happens client-side (a Worker for the heavy formats). This is the pattern documented above.
+
+Parquet, SQLite and CSV/TSV are **server-parsed** instead: the server does the parsing and hands back one page of JSON rows at a time via `GET /api/data-preview/*` (route details in [`dev/api.md`](api.md#data-preview)), so a multi-GB file never has to reach the browser.
+
+```tsx
+// plugins/foo-view.tsx (server-parsed)
+import { useState } from 'react'
+import type { PreviewProps } from '../types'
+import { PreviewShell } from '../ui/preview-shell'
+import { useDataFetch } from '../ui/use-data-fetch'
+import { DataTable } from '../ui/data-table'
+import { api } from '@/shared/api-client'
+
+const PAGE_SIZE = 100
+
+export function FooPreview({ name, path, projectId, downloadUrl, onOpenAsText }: PreviewProps) {
+  const [offset, setOffset] = useState(0)
+  const { data, error, loading } = useDataFetch(
+    projectId ? (signal) => api.dataPreview.foo(path, projectId, offset, PAGE_SIZE, signal) : null,
+    [path, projectId, offset],
+  )
+  return (
+    <PreviewShell name={name} downloadUrl={downloadUrl} onOpenAsText={onOpenAsText} loading={loading} error={error}>
+      {data && (
+        <DataTable
+          columns={data.columns}
+          rows={data.rows}
+          offset={data.offset}
+          limit={data.limit}
+          totalRows={data.totalRows}
+          onPage={setOffset}
+        />
+      )}
+    </PreviewShell>
+  )
+}
+```
+
+Server-parsed plugins need `PreviewProps.projectId` (the workspace absolute path, threaded from editor-panel's two `FilePreview` call sites) to build the `/api/data-preview/*` query.
+
+**Which pattern to pick for a new format**: if the format can be read incrementally on disk (row groups, pages, or lines — like parquet/sqlite/csv), add a route in `data-preview.ts` and go server-parsed — it scales to large files and keeps the browser light. If the format can only be parsed after reading the whole file (zip-based containers like xlsx/docx/pptx), stay raw-bytes; page the fully-parsed result client-side (see xlsx's `DataTable` usage) instead of a hard row cutoff.
+
 ## Server side
 
-All previews fetch via `GET /api/files/download?inline=1` which:
+Raw-bytes previews fetch via `GET /api/files/download?inline=1` which:
 - Streams the file (doesn't read entire buffer into memory)
 - Supports HTTP `Range` (206 Partial Content) for video/audio seek + progressive load
 - Aborts the read when the client disconnects (tab closed / URL changed)
 
+Server-parsed previews fetch via `GET /api/data-preview/*` (schema + one page of rows, `projectId`-scoped like `/api/files/*`).
+
 See [`dev/api.md`](api.md) for the route details.
 
 ## Testing a new plugin