@turmind/halo 1.0.3 → 1.1.0

package/bundled-docs/guide/cli.md

@@ -110,6 +110,12 @@ halo tui -s sid_abc123   # resume session
 halo tui -n              # always start a new session
 ```
 
+`halo tui` needs an interactive terminal — the keyboard layer can't enter raw
+mode without one. When stdin isn't a TTY (CI, `halo tui < file`,
+`echo x | halo tui`) it exits immediately with code 1 and points you at `halo
+cli "<prompt>"`, rather than failing a couple of seconds later inside the
+rendering layer.
+
 Multi-turn conversation. Supports all standard Halo slash commands:
 
 | Command | Description |
@@ -149,9 +155,10 @@ Bare `/<obj>` (or `/<obj> help`) lists the verbs you may run. Verbs gated above
 
 | Key | Action |
 |---|---|
-| `Esc` (while running) | Interrupt the current turn immediately — aborts a command mid-execution, then any messages typed while it was running are folded into one follow-up turn. Same as `/session interrupt`. |
-| `Ctrl+C` | Graceful exit; press twice to force |
-| `Ctrl+O` | Toggle the sub-agent navigator — lists every sub-agent spawned this session, each showing its agent name, task title (same as the session list), and status (`●` running green / `○` idle grey / `✕` stopped red, plus a `▢ archived` marker when the session is archived); `↑↓` to move, `Enter` to view that sub-agent's log, `Esc`/`q` to close. (Was `Shift+Tab`, but Windows terminals consume that as backtab.) The log viewer auto-refreshes while the viewed session is still running (a `● live` hint shows in the header) and follows the bottom as new output lands — unless you've scrolled up to read, in which case it stays put (`G` jumps back to the bottom and resumes following). |
+| `Esc` | **With nothing else open, while a turn is running**: interrupt it immediately — the in-flight tool or command is aborted, then any messages typed while it ran fold into one follow-up turn (same as `/session interrupt`; repeat presses are idempotent, the "interrupting…" notice is throttled). **While the log viewer, the sub-agent navigator, or a completion popup is open**: Esc only closes that surface — a running turn is never touched, so leaving a live log you opened with `Ctrl+O` can't kill it. The popup keeps your typed text when dismissed. Once nothing is open, the next Esc interrupts again. |
+| `Ctrl+C` | Exit — first press arms a confirm (the input hint flips to "press Ctrl+C again to exit" for 1.5s), second press exits. Works even while a modal is open (unlike Esc, nothing swallows it). Exit is graceful: a running turn is stopped, the conversation repaired, and the session flushed to disk. |
+| `Ctrl+O` | Open the session-log navigator (no-op while a log surface is already open) — lists the session tree, the root session plus every sub-agent spawned under it, each showing its agent name, task title (same as the session list), and status (`●` running green / `○` idle grey / `✕` stopped red, plus a `▢ archived` marker when the session is archived); `↑↓` to move, `Enter` to view that session's log, `Esc`/`q` to close. (Was `Shift+Tab`, but Windows terminals consume that as backtab.) Inside the log viewer: `j`/`k` or `↑`/`↓` scroll by line, `d`/`u` (or `Ctrl+F`/`Ctrl+B`, PgDn/PgUp) by half a page, `g`/`G` jump to top/bottom, `q`/`Esc` close. The viewer auto-refreshes while the viewed session is still running (a `● live` hint shows in the header) and follows the bottom as new output lands — unless you've scrolled up to read, in which case it stays put (`G` jumps back to the bottom and resumes following). |
+| `Tab` / `Enter` (popup open) | Complete the highlighted suggestion — slash commands and their verbs while typing `/…`, paths after `@`/`@file`/`@image`/`@scope`. `↑`/`↓` move the highlight; `Esc` dismisses the popup without clearing what you typed (any edit brings it back). A picked directory completes with a trailing `/` and keeps the popup open so you can keep descending; a picked file closes it. With no popup open, Enter submits. |
 | `↑` / `↓` | Walk input history (when no popup is open). History persists across restarts in `~/.halo/global/tui-history.json` (last 100 entries, shared across workspaces) |
 | `←` / `→`, `Home` / `End` | Move the cursor within the input; text is inserted/deleted at the cursor (CJK and emoji safe) |
 | `Ctrl+A` / `Ctrl+E` | Jump to start / end of input |
@@ -176,11 +183,11 @@ Attach files or images to your message with `@file` and `@image`, or pull a dire
 
 - `@file path` — reads the file and inlines its content in the message as `<file>` block
 - `@image path` — reads the image as base64 and sends it via the model's vision input
-- `@file photo.png` — image extensions (`.png`, `.jpg`, `.gif`, `.webp`, `.bmp`) are auto-detected as images
+- `@file photo.png` — image extensions (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`) are auto-detected as images
 - `@scope dir` — injects the directory-scoped `.halo/INSTRUCTIONS.md` along the path from the workspace root down to `dir` (root level excluded — it's already in the system prompt) into **this turn only**. Use it to bring a sub-directory's conventions into scope for one request. It does not change where tools run.
 - Paths are relative to the workspace; absolute paths also work
 - Quoted paths supported for filenames with spaces: `@file "my file.txt"`
-- **Tab completion** in TUI mode: type `@file ` (or `@scope `, which lists directories only) then press Tab to browse
+- **Path completion** in TUI mode: the suggestion popup opens by itself as you type after `@file ` / `@image ` (images and directories only) / `@scope ` (directories only) — `Tab` or `Enter` completes the highlighted entry, directories stay open for descending (see Keybindings)
 
 ### Limits
 
@@ -188,6 +195,18 @@ Attach files or images to your message with `@file` and `@image`, or pull a dire
 - **Images**: skipped if larger than 5MB
 - If the current model does not support vision, a warning is shown and images are ignored
 
+## Server Mode (background daemon)
+
+`halo server start|stop|restart|status|logs` manages a local server from the
+same binary. `start -d` runs it in the background **with a bounded respawn
+supervisor**: the detached process supervises the server and brings it back on
+a crash (non-zero exit, or a kill by anything other than SIGTERM/SIGINT), at
+most 5 times per 5 minutes with a 2s pause, logging each decision as
+`[respawn] …` into `~/.halo/global/logs/server.log`. `halo server stop` is
+recognized as intentional and never respawns; `halo server stop|restart|status`
+still target the server's own pid. Full policy in
+[dev/deploy.md](../dev/deploy.md#crash-semantics--why-restarton-failure-is-load-bearing).
+
 ## Architecture
 
 ```

package/bundled-docs/requirements/chat.md

@@ -21,12 +21,21 @@ The primary surface for talking to an agent.
 Hover actions on user-role turns: the blue sticky user bubble, plus the sub-agent-report (green) and compact-summary (purple) callouts — all three share the same Copy/Delete pair. On the callouts, Copy copies the body only (the `(from: session X)` / `[Conversation Summary…]` marker line is stripped); a deleted callout greys out and gains a "deleted" badge like the bubble does:
 - **Copy** — copies the prompt text to the clipboard
 - **Show more/less** — the existing clamp toggle, shown when the text overflows
-- **Delete** (confirm dialog) — removes the whole exchange (the user turn + all responses up to the next user turn) with **two-layer semantics**: the LLM context (`rawMessages`) drops the turn physically — the model never sees it again, freeing context; the UI keeps the messages, rendered greyed-out with a "deleted" tag, as an audit trail. No undo; a deleted exchange loses its Delete button. Rejected with an error toast while the agent is running or compacting. Root sessions only (sub-session logs don't offer Delete). If the turn was already compacted out of raw context, only the UI marking happens (silent degrade). Design details in [design/session.md](../design/session.md#exchange-deletion-soft-ui--hard-raw), protocol in [design/ws.md](../design/ws.md).
+- **Delete** (confirm dialog) — removes the whole exchange (the user turn + all responses up to the next user turn) with **two-layer semantics**: the LLM context (`rawMessages`) drops the turn physically — the model never sees it again, freeing context; the UI keeps the messages, rendered greyed-out with a "deleted" tag, as an audit trail. No undo; a deleted exchange loses its Delete button. Rejected with an error toast while the agent is running or compacting. Root sessions only (sub-session logs don't offer Delete). If the turn was already compacted out of raw context, only the UI marking happens (silent degrade). Once a session has **archived history** the action is refused for the whole session with a plain explanatory notice (not an `Error:` bubble) — per-turn positions can no longer be mapped once older turns left the active file. Design details in [design/session.md](../design/session.md#exchange-deletion-soft-ui--hard-raw), protocol in [design/ws.md](../design/ws.md).
+
+### Archived history (scroll up to load)
+Long sessions get their older exchanges moved out of the active log on compact, so opening a session stays fast no matter how long it has run. What the user sees:
+
+- A **"Load earlier messages"** row appears above the conversation only for sessions that actually have archived history; it loads one archive chunk per click, oldest-newer order preserved, and becomes **"No earlier messages"** once everything is loaded
+- Scrolling to the very top of the message area triggers the same load automatically (re-armed only after scrolling back down, so one gesture doesn't cascade through the whole archive), and the reading position is preserved when the older messages prepend — the view doesn't jump
+- Loaded history sits in a **collapsed** block ("Archived · N segment(s) · M messages") — the user scrolled up for older context, not to have hundreds of exchanges re-flow the view; expanding renders them like normal messages
+- Archived exchanges are **read-only**: Copy still works, Delete is absent (the server refuses it for archived sessions)
+- Chunks already loaded aren't re-fetched; a failed load can simply be retried with the same row
 
 ### Session sidebar (right side)
 A fixed, collapsible list of the workspace's root sessions on the right edge of the chat panel (terminal-list style, ~200px). Replaces the old popup dropdown — the History button (with count badge) left of the composer and the "N previous sessions" link in the empty state both just toggle it now. Open/collapsed state persists globally in `localStorage` (`halo_session_sidebar_open`), default open.
 
-- Each row: 🎯 goal badge, title, `N msgs · time-ago`, model tail; hover reveals **rename** (pencil) and **delete** buttons; infinite scroll pages older sessions; "+ New Session" footer
+- Each row: 🎯 goal badge, title, `N msgs · time-ago`, model tail; hover reveals **rename** (pencil) and **delete** buttons; infinite scroll pages older sessions; "+ New Session" footer. `N` counts the session's user turns **over its whole lifetime** — compacting or archiving history never makes it go backwards
 - **Inline rename**: pencil → input in place, Enter/blur commits (`PATCH /sessions/logs/:id`), Esc cancels; empty or unchanged title is a no-op. Other session-list consumers refresh via the `session:changed` WS push
 - **Switch loading**: clicking a row shows a spinner on that row + a "Loading session…" state in the message area, cleared only when the server's `state:snapshot` for that exact sessionId arrives (empty sessions included). Past 30s it degrades to "Slow network — still loading…" plus a Retry button (re-subscribes) — slow ≠ failed, nothing aborts on its own
 

package/bundled-docs/requirements/editor.md

@@ -34,14 +34,17 @@ When agents write files through tools, the canvas detects it:
 Open tabs and the active tab live in localStorage; survive refresh.
 
 ### Diff view
-- Tracked files → `GET /api/files/diff` for git diff
+- Tracked files → `GET /api/git/diff` (returns `{ original, modified }`) for git diff
 - Monaco left/right compare view
 
 ### Binary previews
 Non-text files go through `FilePreview`, which looks up a **plugin** in the preview registry by file extension. Built-in plugins:
 - **PDF** — browser-native iframe
 - **DOCX / DOC** — `mammoth` → HTML (parsed in a Web Worker so the UI stays responsive)
-- **XLSX / XLS / CSV** — `xlsx` (SheetJS) → table (parsed in a Web Worker; CSV decoded as UTF-8 with BOM strip)
+- **XLSX / XLS** — `xlsx` (SheetJS) → table, parsed whole in a Web Worker (zip can't stream); rendered with client-side paging (500 rows/page over the in-memory parse — no truncation, just paged)
+- **CSV / TSV** — server-paginated table: each page (100 rows) is parsed and fetched from the server on demand, so large files open instantly. Delimiter is sniffed from the header line (comma/semicolon/tab; `.tsv` forces tab); total row count is a lazy lower bound ("N+") until the last page is reached
+- **Parquet** — server-paginated table (schema + 100-row pages), same pager as CSV/SQLite
+- **SQLite / DB (.db / .sqlite / .sqlite3)** — server-paginated table with a table-selector sidebar (name + row count per table); opened read-only, one page (100 rows) per request
 - **PPTX / PPT** — `pptx-preview` list mode. Fidelity is approximate — complex animations / SmartArt / embedded fonts may not render perfectly; users can download for the exact source. Flagged `heavy: true` so only the *active* pptx mounts (canvas-based rendering needs the main thread). **Speaker-notes sidebar**: notes are extracted from the pptx zip in presentation (play) order and listed on the left; clicking a note scrolls to the corresponding slide (a domIndex mapping bridges play order to pptx-preview's part-filename render order, so reordered decks still land on the right slide). Collapsible with the state remembered in localStorage (`halo.pptxNotesHidden`); the sidebar doesn't appear at all when no slide has notes. Decks with dangling `[Content_Types].xml` overrides (e.g. some WPS exports) are repaired before rendering; if zero slides render anyway, a real error UI is shown instead of a silent black wrapper
 - **Images / video / audio** — native `<img>` / `<video>` / `<audio>`, supports HTTP Range for seek-without-full-download
 

package/bundled-docs/requirements/explorer.md

@@ -43,6 +43,7 @@ Visual directory browser opened by the 📁🔍 button:
 - No max depth limit
 - Expansion state lives in localStorage; restored on refresh and lazily reloaded
 - WebSocket `file:changed` events incrementally update loaded branches; unloaded branches are left alone (re-fetched on expand)
+- **Reconnect reconciliation**: because the tree is kept in sync purely by `file:changed` deltas, events missed while the socket was down (laptop lid, network drop) would leave it stale forever. On WS *re*connect (not first connect) the root level is silently refetched; expanded directories self-heal because their fresh nodes come back without children, which re-arms the lazy-load along the persisted expanded-paths spine
 
 ### Selection model
 VS Code-style highlight selection (no checkboxes):

package/bundled-docs/requirements/session.md

@@ -6,7 +6,7 @@ Session history viewer: hierarchy tree, message playback, debug mode, system pro
 
 ### Session tree view
 - Top-level sessions (no parentSessionId) act as roots; child sessions render indented
-- Each row shows: title, agent-name badge, message count, relative time, and status icons (StopCircle for stopped, amber Archive for archived)
+- Each row shows: title, agent-name badge, message count (user turns over the session's lifetime — never shrinks when history is compacted/archived), relative time, and status icons (StopCircle for stopped, amber Archive for archived)
 - Clicking loads the full message list into SessionChatPanel
 - Collapse / expand via arrow buttons
 - Clicking the count badge (e.g. "+3") shows total descendant count
@@ -35,8 +35,8 @@ The Prompt button (FileText icon) shows the system prompt used by this session.
 - Created on the first `chat` WS message (with a new sessionId)
 - Auto-saved after every `complete` event
 - Sessions restore from disk on refresh / WS reconnect (loaded at subscribe time; running sessions reattach from the detached pool)
-- Deleting a session removes the JSON file and cascade-deletes all descendants in SQLite
-- Assistant messages embed a `toolCalls` array so tool-call cards persist across refresh
+- Deleting a session removes the JSON file (plus any archived history segments) and cascade-deletes all descendants in SQLite
+- Assistant messages persist their `contentBlocks` (text / thinking / tool calls, in the order they happened) so tool-call cards survive a refresh in the right places. Sessions written before content blocks existed carry a flat `toolCalls` array instead and still render, as a fallback
 
 ### Non-destructive /session new
 `/session new` (session:clear) **does not** destroy the old session:
@@ -63,6 +63,7 @@ Unified session logs API (recommended):
 |---|---|
 | List | `GET /api/sessions/logs?projectId=...` |
 | Read | `GET /api/sessions/logs/:id?projectId=...` |
+| Read archived history | `GET /api/sessions/logs/:id/archive/:n?projectId=...` |
 | Delete | `DELETE /api/sessions/logs/:id?projectId=...` |
 
 The List endpoint serves two consumers: this tree view (default — roots + all

package/bundled-docs/requirements/source-control.md

@@ -46,6 +46,7 @@ The panel, the history graph, and the Explorer git decorations all refresh on th
 
 - **Panel-driven writes**: every git mutation route (stage/unstage/commit/push/pull/init/remote) re-broadcasts `file:changed` (path `.git`) itself, because the workspace file watcher deliberately ignores `.git`. So after a commit the CHANGES list auto-clears with no manual refresh.
 - **Command-line writes**: a lightweight, **non-recursive** watch on the `.git` directory's top-level `HEAD` / `index` files (separate from the recursive workspace watcher, which excludes `.git` to avoid being overwhelmed by object-store inodes) catches terminal `git commit` / `checkout` / `add` / `reset` and broadcasts the same `file:changed`. `.lock` churn is filtered; the operation's events are debounced into a single refresh. So a commit made in the integrated terminal updates the panel without a manual refresh.
+- **Reconnect reconciliation**: `file:changed` is a fire-and-forget push, so anything that happened while the socket was down (laptop lid, network drop) is simply lost. Panel, history graph and Explorer decorations therefore also refresh once on WS *re*connect (first connect is skipped — the initial load already fetched), which is the only way a terminal commit made during the outage shows up without a manual refresh.
 - **Two-phase watcher**: `GitDirWatcher` adapts to whether the workspace is a repo yet. A real work-tree watches `.git` directly (the steady state above). A **non-git folder** instead watches the workspace *root* (still non-recursive) for one thing only — `.git` appearing — so a terminal `git init` / `git clone` is noticed and upgrades the watcher onto `.git`, firing once so the [entry auto-surfaces](#entry-visibility-git-gated). The root-watch handler compares the event filename before any disk IO (ordinary file churn costs one string compare), and a real repo never enters this degraded mode.
 
 ## Explorer git decorations