@turmind/halo 1.5.4 → 1.5.6

package/bundled-docs/requirements/terminal.md

@@ -5,11 +5,11 @@ xterm.js terminal with a node-pty backend, multi-tab, reconnect-resilient.
 ## Core behaviour
 
 ### Multi-tab
-- Each tab owns an independent PTY
+- Each tab owns an independent PTY; the first one is spawned only when the Terminal tab is first opened
 - Every terminal has a unique `terminalId` for routing
 - Tabs close independently
 - All tabs on a client share one WebSocket connection (multiplexed by `terminalId`)
-- The tab list is a column of Chrome-style **vertical tabs** on the right of the terminal (same `VerticalTabList` + `ResizableSidebar` components as the chat session tabs). Each row has a terminal icon and its name, and a ✕ to close it, shown while more than one terminal is open. A "+" at the bottom opens a new terminal
+- The tab list is a column of Chrome-style **vertical tabs** on the right of the terminal (same `VerticalTabRow` / `ResizableSidebar` components as the chat session tabs). Each row has a terminal icon and its name, and a ✕ that closes just that terminal; it appears on hover only, and not at all while a single terminal is left. A "+" at the bottom opens a new terminal
 - The list can be **resized** by dragging its left edge (120–480px, default 160px), and **collapsed** to a `w-10` rail of square icons with a "+" at the bottom. Both settings persist globally in `localStorage` (`halo_terminal_sidebar_open`, `halo_terminal_sidebar_width`)
 
 ### Working directory
@@ -17,12 +17,12 @@ xterm.js terminal with a node-pty backend, multi-tab, reconnect-resilient.
 | Scenario | Initial cwd |
 |---|---|
 | Default workspace terminal | Current project's workspace root (`activeProject.path`) |
-| Skill mini-workspace terminal | The skill directory (cwd prop passed by caller) |
+| Explorer context menu → open in terminal | A new terminal in the right-clicked folder (or the file's parent) |
 | No workspace bound | `?folder=` URL param, falling back to server `$HOME` |
 
-Derivation in [packages/admin/src/features/terminal/terminal-panel.tsx:108](../../../packages/admin/src/features/terminal/terminal-panel.tsx#L108); backend resolution in [packages/server/src/ws/terminal-manager.ts:46](../../../packages/server/src/ws/terminal-manager.ts#L46).
+Derivation in `createTerminal` in [packages/admin/src/features/terminal/terminal-panel.tsx](../../../packages/admin/src/features/terminal/terminal-panel.tsx); backend resolution in `TerminalManager.start` in [packages/server/src/ws/terminal-manager.ts](../../../packages/server/src/ws/terminal-manager.ts).
 
-Workspace switch does **not** migrate existing terminals — they keep their original cwd. Close and reopen to pick up the new workspace root.
+Workspace switch reloads the page and does **not** migrate existing terminals — they keep their original cwd and are only reattached in their own workspace (within the grace period); the new workspace starts a fresh terminal at its root.
 
 ### Reconnect resilience
 
@@ -31,19 +31,19 @@ When the WebSocket drops:
 1. PTYs are **not killed** — they stay in the module-level `terminals` map with `currentWs = null` (`packages/server/src/ws/terminal-manager.ts`)
 2. Output during detach is buffered (ring buffer, up to `config.limits.terminalOutputBuffer` = 50 KB per terminal)
 3. Grace period: `config.timeout.terminalGrace` (default 5 min)
-4. On reconnect, the client sends `terminal:reattach` (sent on initial mount **and** on every subsequent `_connected` event)
+4. On reconnect, the client sends `terminal:reattach` with its `browserId` and workspace path (sent on initial mount **and** on every subsequent `_connected` event); only PTYs of that browser × workspace are claimed
 5. Server replays the entire output buffer, reattaches live I/O, and responds with `terminal:reattached { terminalIds: [...] }`
 6. If the grace timer expires first, the PTY is killed and the detach entry removed
 
 Connection-level liveness and reconnect (server keepalive tolerance, client self-check timer, auth-expiry handling) are owned by the shared WS client — see [design/ws.md](../design/ws.md#client-side-liveness--reconnect).
 
-On the reattach handler ([packages/admin/src/features/terminal/terminal-panel.tsx](../../../packages/admin/src/features/terminal/terminal-panel.tsx)), each id in `terminalIds` is dispatched by whether a local xterm instance already exists:
+When the WS drops, the bottom panel remounts `TerminalPanel` (fresh key on `_disconnected`): local xterm instances are disposed without sending `terminal:close`, and the new panel reattaches like a page load. The local scrollback is lost; the server replays only what was buffered while detached. On the reattach handler ([packages/admin/src/features/terminal/terminal-panel.tsx](../../../packages/admin/src/features/terminal/terminal-panel.tsx)), each id in `terminalIds` is dispatched by whether a local xterm instance already exists:
 
-- **Already exists** (typical after a transient WS reconnect): only a `terminal:resize` is sent so server PTY dimensions resync; the existing instance keeps its scrollback and continues receiving live output.
-- **Does not exist** (first mount, or the previous instance was disposed): a fresh xterm container is created and bound to that id. Bracketed paste mode is resynced by locally writing `\x1b[?2004h` into the new instance — bash enabled the mode on the PTY at spawn time, but that sequence went to the disposed instance; without the resync, a multi-line paste into the reattached terminal would be sent unbracketed and execute line by line.
+- **Already exists** (a reattach without a remount): only a `terminal:resize` is sent so server PTY dimensions resync; the existing instance keeps its scrollback and continues receiving live output.
+- **Does not exist** (first mount, or after the remount above): a fresh xterm container is created and bound to that id. Bracketed paste mode is resynced by locally writing `\x1b[?2004h` into the new instance — bash enabled the mode on the PTY at spawn time, but that sequence went to the disposed instance; without the resync, a multi-line paste into the reattached terminal would be sent unbracketed and execute line by line.
 
 ### Environment
-- Shell: `$SHELL` or `/bin/bash`
+- Shell: `$SHELL` or `/bin/bash` (`ComSpec` / `powershell.exe` on Windows); bash / zsh / sh / fish start as login shells (`-l`)
 - Terminal type: `xterm-256color`
 - Default size: 80 × 24 (resize requests override)
 - Strips `npm_config_prefix` env (avoids nvm warnings when starting node)
@@ -95,7 +95,7 @@ Source: [packages/server/src/ws/terminal-manager.ts](../../../packages/server/sr
 | Config key | Default | Purpose |
 |---|---|---|
 | `config.timeout.terminalGrace` | 300,000 ms | Detach retention period |
-| `config.limits.terminalOutputBuffer` | 50,000 bytes | Detach output ring buffer cap |
+| `config.limits.terminalOutputBuffer` (setting `general.limits.terminal_scrollback_bytes`) | 50,000 bytes | Detach output ring buffer cap |
 
 Defined in [packages/server/src/config.ts](../../../packages/server/src/config.ts).
 
@@ -104,12 +104,12 @@ Defined in [packages/server/src/config.ts](../../../packages/server/src/config.t
 | # | Scenario | Expected |
 |---|---|---|
 | T1 | Start, run `ls` | Output arrives; prompt returns |
-| T2 | Start in skill mini-workspace | cwd is the skill directory (`pwd` confirms) |
+| T2 | Explorer → right-click a folder → Open in Integrated Terminal | A new terminal whose cwd is that folder (`pwd` confirms) |
 | T3 | Resize window | PTY cols/rows update; long-running process (e.g. `watch ls`) reflows |
 | T4 | Disconnect mid-command (`sleep 5 && echo done`) → reconnect within grace period | Buffered output replayed; `done` visible |
 | T5 | Disconnect → wait > grace period → reconnect | Terminal gone (PTY killed at grace expiry) |
 | T6 | Open 3 tabs, close 1 explicitly | Other 2 keep their PTYs; closed one gets `terminal:exit` |
-| T7 | `exit` from within shell | `terminal:exit` with exitCode=0; tab shows closed |
+| T7 | `exit` from within shell | `terminal:exit` with the shell's exit code; the terminal prints `[Process exited]` and its tab stays until closed |
 | T8 | Paste a 10 KB block | Sent as `terminal:input` without choking; shell echoes in chunks |
 
 Follows the pattern of [test/session.md](../test/session.md).

package/bundled-docs/requirements/workspace.md

@@ -1,10 +1,10 @@
 # Workspace Layout — Requirements
 
-Overall workspace layout: Activity Bar + Sidebar + main content + a resizable bottom panel.
+Overall workspace layout: Activity Bar + Sidebar + main content; the Explorer tab adds a resizable bottom panel.
 
 ## Layout structure
 
-Most tabs use the standard layout (with bottom panel):
+The Explorer tab uses the layout with the docked bottom panel:
 
 ```
 +---+-------------+---------------------------+
@@ -22,22 +22,27 @@ Most tabs use the standard layout (with bottom panel):
 +---+--------------+---------------------------+
 ```
 
-**Skills** is an exception — SkillsMain (file tree + Canvas) uses the full height, no bottom panel.
+Every other tab uses the full height with no docked bottom panel (Skills: SkillsMain = file tree + Canvas).
 
-The Bottom Panel (Chat + Terminal) can also be **floated** into a draggable window that survives activity-tab switching — see "Bottom panel" below.
+The Bottom Panel (Chat + Terminal) can also be **floated** into a draggable window that survives activity-tab switching, or **maximized** over the whole viewport — see "Bottom panel" below.
 
 ## Activity Bar tabs
 
 | Icon | Tab | Sidebar | Main content | Bottom panel |
 |---|---|---|---|---|
 | FolderTree | Explorer | File tree + ops | Canvas (Monaco + previews) | Chat + Terminal |
-| MessageSquare | Sessions | Session list | Session message viewer | Chat + Terminal |
+| GitBranch | Source Control | Changes + commit box | Diff / history graph | — |
+| MessageSquare | Sessions | Session list | Session message viewer | — |
 | Zap | Skills | Skill list | SkillsMain (full height) | — |
-| Bot | Agents | — | Agent config editor + Test (full width) | Chat + Terminal |
-| MessageCircle | Channels | Channel list | Channel config editor | Chat + Terminal |
-| Sparkles | Evolution | — | Evolution main (run/apply review) | Chat + Terminal |
-| Clock | Cron | — | Cron job list + run audit | Chat + Terminal |
-| Settings2 | Settings | — | Settings panel | Chat + Terminal |
+| Bot | Agents | — | Agent config editor + Test (full width) | — |
+| MessageCircle | Channels | Channel list | Channel config editor | — |
+| Sparkles | Evolution | Run list + status filters | Evolution main (run/apply review) | — |
+| Clock | Cron | Job list | Cron job detail / form + run audit | — |
+| Settings2 | Settings | — | Settings panel | — |
+
+The Source Control entry is hidden in workspaces that are not git repos.
+
+Below Settings sits the quick-toggles entry (network status, finish notification, and on desktop pin / keep-screen-awake) — see [explorer.md → Desktop windows](explorer.md#desktop-windows-multi-window).
 
 ## Resizable panels
 - **Sidebar width**: drag between sidebar and main content
@@ -53,12 +58,12 @@ Two tabs:
 Current tab stored in `editorStore.bottomTab`.
 
 ### Floating mode
-The tab bar has a float button on the far right. Toggling it detaches the panel into a draggable window:
+The tab bar has a maximize button and, at the far right, a float button. Toggling the float button detaches the panel into a draggable window:
 - **Default position/size**: bottom-right corner, 480×640 with a 24px margin
 - **Drag**: grab the tab bar (anywhere except buttons) to reposition
 - **Resize**: four edges (N/S/E/W) + four corners (NW/NE/SW/SE), minimum size 320×240
 - **Visible from any activity tab** — Explorer's in-layout bottom panel is hidden while floating; Canvas takes full height
-- **Only one instance** mounted at a time (xterm DOM gets rebuilt once on dock/undock; server-side terminal sessions are preserved and reattached, scroll buffer is lost)
+- **Only one instance** is mounted; dock / undock / maximize just move it, so terminals and their scroll buffers survive
 - **State is in `sessionStorage`** (`halo_bottom_floating` + `halo_bottom_float_rect`) — page refresh reverts to docked mode
 - **Agent "Test" button** dispatches `halo:navigate → explorer` to surface Chat; this jump is suppressed while floating since Chat is already globally visible
 - **Close (✕) button** on the float window's tab bar docks it back
@@ -69,7 +74,8 @@ The tab bar has a float button on the far right. Toggling it detaches the panel
 |---|---|
 | Cmd/Ctrl + P | Quick Open (fuzzy file search) |
 | Cmd/Ctrl + S | Save current file |
-| Alt + W | Close current tab (Cmd+W cannot be overridden in browsers) |
+| Cmd/Ctrl + ` | Toggle the bottom panel between Chat and Terminal |
+| Alt + W | Close current tab (Cmd+W cannot be overridden in browsers; the desktop app uses Cmd/Ctrl + W) |
 
 ## Auth