@turmind/halo 1.5.4 → 1.5.5

package/bundled-docs/requirements/session.md

@@ -6,12 +6,12 @@ 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 (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
+- Each row shows: title, message count (user turns over the session's lifetime — never shrinks when history is compacted/archived), relative time, and status icons (amber Archive for archived; StopCircle for stopped, sub-agent rows only). Sub-agent rows also carry an agent-name badge; a root row shows an "active" badge when it is the chat panel's current session
+- Clicking a row previews its full message list in SessionChatPanel; double-clicking a root row opens it in an Explorer chat tab
+- Collapse / expand via the arrow buttons; a row with descendants shows a non-clickable "+N" total descendant count
+- Hover trash on a root row (confirm dialog) hard-deletes the session and its whole subtree via REST
 - Inline title rename (admin-only): a hover pencil on any row — root **or** sub-agent — opens an inline input (Enter commits, Escape cancels, blur commits); persists via `PATCH /api/sessions/logs/:id`
-- Infinite scroll loads more roots in pages; a silent reload (after streaming ends, or a delete / create / archive elsewhere) re-fetches the **same depth** already scrolled to rather than snapping back to the first page. No cap on depth: a reload deeper than the endpoint's 500-row page limit pages through with the cursor in 500s and renders once at the end (the 300-top-level cap was removed in 1.5.3-alpha)
+- Infinite scroll loads more roots in pages; a silent reload (after streaming ends, or a delete / create / archive elsewhere) re-fetches only the first page and merges it over the rows already loaded, so the list keeps its depth and scroll position. Rows beyond the first page aren't re-checked until the next full reload (mount / project switch). No cap on depth (the 300-top-level cap was removed in 1.5.3-alpha)
 - Viewed sessions are cached (LRU, 20 sessions; the one on screen is never evicted): switching back to a cached session shows the kept copy at once — transcript, archive position and reading position — and a stale copy (its log file changed, or the WS reconnected) is refetched in the background. Refetches are single-flight per session: at most one request in flight plus one queued re-pull. A session that is open in an Explorer chat tab shows that tab's live stream instead
 - The Sessions tab mounts on first open and then stays mounted (CSS-hidden while another activity tab is up), so the cache and reading positions survive switching tabs
 
@@ -22,29 +22,27 @@ Session history viewer: hierarchy tree, message playback, debug mode, system pro
 - For a session whose history was compacted, scrolling to the top shows a "load earlier messages" row; scrolling further or clicking it pulls one archived segment at a time. Pulled history renders expanded above the active log, with a divider marking where it ends, and is read-only (no delete)
 
 ### Debug mode
-Top Debug toggle (Bug icon). When on:
-- **Normal mode**: user message + assistant reply (with inline tool-call cards); sub-agent notifications hidden
-- **Debug mode**: every message, including:
-  - **Context / System Prompt** (purple) — full injected prompt, expandable
-  - **Tool Call** (blue) — full tool input JSON, expandable
-  - **Tool Result** (green/red) — full tool output JSON, expandable
-  - **Usage** — token counts, latency (ttft / e2e), model ID, cache hit ratio
-  - Sub-agent messages carry an agent-name badge
+Top Debug toggle (Bug icon), persisted in `localStorage` as `halo_session_debug`. When on:
+- **Normal mode**: user message + assistant reply (with inline tool-call cards, click to expand IN / OUT); sub-agent notifications hidden
+- **Debug mode**: adds, on top of the normal view:
+  - **Thinking** blocks (purple, expandable, with char count) inside assistant messages
+  - **Usage** line after each turn — timestamp, token counts (in / out / ctx, cache read / write / hit ratio), latency (ttft / e2e), thinking effort, model ID
+  - Sub-agent start / done markers labelled with the agent name
 
 ### System prompt viewer
-The Prompt button (FileText icon) shows the system prompt used by this session. Extracted from the first `context`-type message; displays the full injected prompt (AGENT.md + INSTRUCTIONS.md + INDEX.md + TOOL_GUIDELINES + skills).
+The Prompt button (FileText icon, shown only when the session has a prompt; open state persisted as `halo_session_prompt`) shows the system prompt used by this session in a floating card. Extracted from the first `context`-type message (never rendered inline in the list); displays the full injected prompt (AGENT.md + INSTRUCTIONS.md + INDEX.md + TOOL_GUIDELINES + skills).
 
 ### Session lifecycle
 - 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 (plus any archived history segments) and cascade-deletes all descendants in SQLite
+- Deleting a session removes the JSON file (plus any archived history segments) and cascade-deletes all descendants (their files and SQLite rows)
 - 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` (also `/clear` and "+ New Session") **does not** destroy the old session:
 1. A new draft tab opens in the chat panel with an empty conversation; the session is created on its first message or command
-2. The old session keeps its tab and keeps streaming into it in the background (its row shows a running mark, and an unread dot once new output lands)
+2. The old session keeps its tab and keeps streaming into it in the background (its row's status dot pulses amber while it runs and turns blue once new output lands unseen)
 3. The old session's sub-agents keep running independently
 4. Switching back shows the old tab as it is; after a reconnect it reloads from the server
 
@@ -56,7 +54,7 @@ The Prompt button (FileText icon) shows the system prompt used by this session.
 |---|---|
 | Main session | Sidebar top level |
 | Child session (has parentSessionId) | Nested under parent |
-| Stopped session | Icon decorated with StopCircle |
+| Stopped session (sub-agent row) | Icon decorated with StopCircle |
 | Archived session | Shown dimmed (50% opacity) with an amber Archive icon — the list fetches `includeArchived=1`, so archived rows stay visible for inspection rather than being hidden |
 
 ## API
@@ -69,6 +67,7 @@ Unified session logs API (recommended):
 | 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=...` |
+| Rename | `PATCH /api/sessions/logs/:id?projectId=...` (body `{title}`) |
 
 The List endpoint serves two consumers: this tree view (default — roots + all
 descendants, paginated, rebuilt into a tree client-side) and the chat panel's

package/bundled-docs/requirements/settings.md

@@ -17,8 +17,8 @@ general:                                  # built-in declarer (server itself)
     max_summary_input: 15000
     ...
   sandbox:
-    hidden_dirs: "~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker,~/.config/gh"
-    hidden_files: "~/.npmrc,~/.bash_history,~/.gitconfig,~/.git-credentials,~/.netrc,~/.halo/global/runs.db"
+    hidden_dirs: "~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker,~/.config/gh,~/.halo/global/internal-sessions,~/.halo/global/logs"
+    hidden_files: "~/.npmrc,~/.bash_history,~/.gitconfig,~/.git-credentials,~/.netrc,~/.halo/global/evo.db,~/.halo/global/evo.db-wal,~/.halo/global/evo.db-shm,~/.halo/global/cron.db,~/.halo/global/cron.db-wal,~/.halo/global/cron.db-shm,~/.halo/global/runs.db,~/.halo/global/runs.db-wal,~/.halo/global/runs.db-shm"
     writable_dirs: ""                     # e.g. ~/.kiro,~/.local/share/kiro-cli — rw bind-mounts in bwrap; ignored for readonly sessions
   logging:
     level: warn
@@ -36,13 +36,13 @@ deepseek:
   secrets:
     api_key: <<DEEPSEEK_API_KEY>>
 
-tavily-search:                            # skill id from skills/<id>/config.yaml
+tavily-web-search:                        # skill id from skills/<id>/config.yaml
   params:
     api_key: <<TAVILY_API_KEY>>
 ```
 
 The path always reads as `<namespace-id>.<kind>s.<key>`:
-- `<namespace-id>` is `general`, a provider id, or a skill id
+- `<namespace-id>` is `general`, a provider id, a skill id, or an agent id
 - `<kind>` is `param` or `secret`
 - `<key>` is the leaf, dotted for grouping (e.g. `general.compact.keep_messages`)
 
@@ -91,15 +91,17 @@ params:
 secrets: []
 ```
 
+Global agents declare theirs the same way in `agents/<agent-id>/agent-config.yaml` (same `params:` / `secrets:` lists; shown under Settings → Agents).
+
 ### General — built-in
 
-Declared in [packages/server/src/settings-schema.ts](../../../packages/server/src/settings-schema.ts) `generalSection()`. The server itself is the implicit declarer. Keys: `language`, `agent.*`, `server.*`, `session.*`, `compact.*`, `sandbox.*`, `logging.*`, `evolution.*`, `limits.*`. All `general.*` keys are `globalOnly`: `config.ts` resolves them through `settingsValue()` against `~/.halo/secrets/settings.yaml` only, so a workspace `settings.yaml` cannot override them. Per-workspace layering applies to namespaced `params` / `secrets` (`getServerSecret(ns, key, workspaceRoot)`, `substituteSecrets`).
+Declared in [packages/server/src/settings-schema.ts](../../../packages/server/src/settings-schema.ts) `generalSection()`. The server itself is the implicit declarer. Keys: `language`, `theme`, `agent.*`, `server.*`, `session.*`, `compact.*`, `sandbox.*`, `logging.*`, `observability.*` (read once at boot — restart to apply), `evolution.*`, `limits.*`. All `general.*` keys are `globalOnly`: `config.ts` resolves them through `settingsValue()` against `~/.halo/secrets/settings.yaml` only, so a workspace `settings.yaml` cannot override them. Per-workspace layering applies to namespaced `params` / `secrets` (`getServerSecret(ns, key, workspaceRoot)`, `substituteSecrets`).
 
 `server.trust_proxy` (boolean, default `false`, `globalOnly`): whether the brute-force rate limiter (`middleware/brute-force.ts` `getClientIp`) trusts the `x-forwarded-for` header for client IP resolution. Direct-connect deployments leave it `false` and get the socket address. Behind a reverse proxy (nginx / Cloudflare / etc.), set it to `true` so the real client IP is honored instead of the proxy's — but only when that proxy is one you control and rewrites the header itself, otherwise a client can forge XFF to dodge lockouts.
 
 `sandbox.hidden_dirs` / `sandbox.hidden_files` / `sandbox.writable_dirs` are `globalOnly` — they define the security boundary agents run inside, so a workspace `settings.yaml` cannot override them (a workspace overriding them could lift its own sandbox constraints).
 
-`evolution.*` controls the self-evolution subsystem (see [plans/self-evolution.md](../plans/self-evolution.md)). All `evolution.*` keys are `globalOnly` — they live in `~/.halo/secrets/settings.yaml` only, not workspace settings. Notable knobs: `evolution.level` (`L0` = off, `L1` = human + LLM assist), `evolution.max_concurrent_run` / `max_concurrent_apply` (wrapper concurrency caps), `evolution.run_timeout_minutes` / `apply_timeout_minutes` (heartbeat timeouts), `evolution.max_attempts` (per-row retry cap), `evolution.triggers.pre_compact` (snapshot session before compaction).
+`evolution.*` controls the self-evolution subsystem (see [design/evolution.md](../design/evolution.md)). All `evolution.*` keys are `globalOnly` — they live in `~/.halo/secrets/settings.yaml` only, not workspace settings. Notable knobs: `evolution.level` (`L0` = manual only: `/evo` drafts, a reviewer approves; `L1` = L0 plus automatic drafting on pre-compact), `evolution.max_concurrent_run` / `max_concurrent_apply` (wrapper concurrency caps), `evolution.run_timeout_minutes` / `apply_timeout_minutes` (heartbeat timeouts), `evolution.max_attempts` (per-row retry cap), `evolution.triggers.pre_compact` (snapshot session before compaction).
 
 Goal mode's entry points are offline (the `/goal` command, admin banner and creation of new goal sessions are hidden). To reopen them, set `general.goal_mode_enabled` — a global-only boolean, default `false`, read from `~/.halo/secrets/settings.yaml` only (a workspace `settings.yaml` has no effect) and not shown in the Settings UI — then restart the Halo server and refresh the browser (existing goal bindings and history are not touched either way):
 
@@ -117,11 +119,13 @@ The value is read once at process start, so unlike other settings it is **not**
 | Attribute | Required | Purpose |
 |---|---|---|
 | `key` | yes | Leaf key under the namespace |
+| `type` | no | `string` (default) / `int` / `float` / `boolean` / `enum` — picks the input widget |
+| `options` / `optionLabels` | no | For `type: enum`: the allowed values, and optional display labels parallel to them |
 | `description` | no | English description rendered as help text |
 | `description_zh` | no | Chinese description (UI picks based on lang) |
 | `default` | no | Placeholder shown when the value is unset; supports `<<ENV>>` |
 | `secret` | no | `true` → masked in API responses + password input in UI |
-| `globalOnly` | no | `true` → read from global settings only; workspace overrides are ignored at runtime. UI disables the workspace input and shows a "global only" hint |
+| `globalOnly` | no | `true` → read from global settings only; workspace overrides are ignored at runtime. UI disables the workspace input and shows a "global only" hint; `PUT` / `PATCH` / `DELETE` of such a key at workspace scope is rejected with 400. Set by the built-in `general` section only — provider / skill / agent yaml declarations don't read it |
 
 ## Scope: global vs. workspace
 
@@ -133,7 +137,8 @@ The value is read once at process start, so unlike other settings it is **not**
 Read order: `<schema default> <- <global> <- <workspace>` (workspace layer applies to namespaced `params` / `secrets` only — see General above).
 
 The Settings page shows source badges per field:
-- `workspace` (green-blue, override applied here)
+- `workspace` (blue, override applied here)
+- `global` (green, value set at the global layer)
 - `inherited from global` (grey, value pulled from global because workspace has none)
 - `unset` (no value at any layer; the `default` is shown as placeholder)
 
@@ -147,7 +152,7 @@ Values can carry `<<ENV_NAME>>` placeholders. They're expanded:
 
 **Trust boundary**: `<<ENV>>` is only expanded inside settings-resolved values. Raw cmd text the agent writes is not scanned — `shell_exec "echo <<HOME>>"` keeps the literal. This prevents an agent from naming an env var and forcing the server to dump it.
 
-Env var unset → the `<<ENV_NAME>>` literal stays verbatim, plus `[md-vars] Env var "X" not set — keeping <<X>> literal` in the server log. The Settings UI returns the literal too — the browser never sees the real env value.
+Env var unset → the `<<ENV_NAME>>` literal stays verbatim, plus `[MdVars] Env var "X" not set — keeping <<X>> literal` in the server log. The Settings UI returns the literal too — the browser never sees the real env value.
 
 ## Agent visibility
 
@@ -169,7 +174,7 @@ A malicious skill that tries `curl -H "Bearer {{aws-bedrock-claude-invoke.secret
 
 ## Orphans
 
-Values present in `settings.yaml` whose namespace doesn't appear in any current schema declaration are surfaced as **orphans** in a dedicated tab. They aren't deleted automatically — uninstalling a skill keeps its values around so re-installing pops them back in. Users prune them on their own schedule via the orphan tab's per-key Remove buttons.
+`params` / `secrets` values present in `settings.yaml` that no current schema declaration covers (the whole namespace is gone, or just that key) are surfaced as **orphans** in a dedicated tab. They aren't deleted automatically — uninstalling a skill keeps its values around so re-installing pops them back in. Users prune them on their own schedule via the orphan tab's per-key Remove buttons.
 
 `general.*` is intentionally excluded from orphan detection — its declared keys are enumerated by the built-in schema, so anything else there is treated as either a typo or a forward-compat field, not an orphan.
 
@@ -177,7 +182,7 @@ Values present in `settings.yaml` whose namespace doesn't appear in any current
 
 A **Security** entry in the left nav (below the System group) opens a page with two cards. Like `__orphans` it's a synthetic nav target, not a schema section — the credential lives in `~/.halo/secrets/config.yaml` (`server.password`, scrypt hash), not `settings.yaml`, and the header shows that path accordingly.
 
-**Change password** — three inputs: current password, new password, confirm. Live client-side feedback while typing: strength rule (≥8 chars, at least one letter and one digit), new ≠ current, confirm matches; the submit button stays disabled until all pass. Submit posts to `POST /api/auth/change-password` (see [dev/api.md](../dev/api.md)) — the server re-runs the same checks authoritatively; a server rejection is shown verbatim under the form. Success shows an inline confirmation and clears all three fields. Existing sessions stay signed in (`jwt_secret` is not rotated). Forgotten password (can't provide the current one) is out of scope here — that's `halo setup`'s reset path.
+**Change password** — three inputs: current password, new password, confirm. Live client-side feedback while typing: strength rule (≥8 chars, at least one letter and one digit), new ≠ current, confirm matches; the submit button stays disabled until all pass. Submit posts to `POST /api/auth/change-password` (see [dev/api.md](../dev/api.md)) — the server re-runs the same checks authoritatively; a server rejection is shown verbatim under the form. Success shows an inline confirmation and clears all three fields. When the password is supplied by the `HALO_PASSWORD` env var the endpoint refuses with 400, since the stored hash is not what login checks. Existing sessions stay signed in (`jwt_secret` is not rotated). Forgotten password (can't provide the current one) is out of scope here — that's `halo setup`'s reset path.
 
 **Log out** — the login state is an httpOnly JWT cookie, so JS can't clear it directly: the button calls `POST /api/auth/logout` (server expires the cookie via Set-Cookie) and reloads; the boot auth check then lands on the login page. This browser only — no server-side token blacklist.
 
@@ -185,7 +190,6 @@ A **Security** entry in the left nav (below the System group) opens a page with
 
 | Operation | Method | Endpoint | Purpose |
 |---|---|---|---|
-| Read merged settings (legacy) | GET | `/api/settings?projectId=xxx` | Raw read, used by older tooling |
 | Read schema + resolved values | GET | `/api/settings/schema?projectId=xxx` | Drives the new Settings page |
 | Replace scope | PUT | `/api/settings` | Bulk replace one yaml file |
 | Patch single key | PATCH | `/api/settings` | Set a leaf at `<dotted-key>` |
@@ -208,7 +212,7 @@ A **Security** entry in the left nav (below the System group) opens a page with
           "kind": "secret",
           "description": "AWS Access Key ID",
           "description_zh": "...",
-          "default": null,
+          "default": "...",                        // omitted when the schema declares none
           "secret": true,
           "value": "AK****ST",
           "hasValue": true,
@@ -237,7 +241,7 @@ A **Security** entry in the left nav (below the System group) opens a page with
 
 ### DELETE body
 
-Same shape minus `value`. Removes the leaf at `key`. For Reset behaviour: workspace scope DELETE → field falls back to global / default; global scope DELETE → field becomes unset.
+Same shape minus `value`. Removes the leaf at `key`. For Reset behaviour: workspace scope DELETE → field falls back to global / default; global scope DELETE → field becomes unset. Like PUT / PATCH it fires the settings-change notification; deleting a key that is already absent is a no-op (no write, no notification). Like PATCH, a `globalOnly` key at workspace scope is rejected with 400 and the file is left untouched.
 
 ## i18n
 

package/bundled-docs/requirements/skill.md

@@ -35,11 +35,11 @@ button is hidden in this mode (`showMaximize={false}`).
 ### Management UI
 
 The Skills sidebar mirrors the Agents sidebar layout:
-- Two collapsible sections — **Global** (globe icon) and **Workspace** (folder icon). Expanded state persists in `halo_skills_expandedScopes` (localStorage)
+- Two collapsible sections — **Global** (globe icon) and **Workspace** (folder icon, shown only while a workspace is open). Expanded state persists in `halo_skills_expandedScopes` (localStorage)
 - Each section header has its own **+ button** — scope is implicit from which button is clicked, no pop-up picker
 - Creating a name that collides with the other scope prompts a one-time confirmation explaining the runtime override
 - Items overridden by a workspace skill are rendered dimmed with "overridden" subtitle
-- Disabled skills are rendered dimmed with "disabled" subtitle and a toggle switch (always visible). Disabled state is stored per workspace in the `disabled_items` table of `halo.db` (not in SKILL.md frontmatter). Both global and workspace skills can be independently toggled per workspace. Disabled skills are excluded from system prompt injection, activate_skill tool, agent form skill picker, and `/workspace share` export.
+- Each row has a toggle switch (shown on hover while enabled, always visible once disabled) and a hover trash button. Disabled skills are rendered dimmed with "disabled" subtitle. Disabled state is stored per workspace in the `disabled_items` table of `halo.db` (not in SKILL.md frontmatter). Both global and workspace skills can be independently toggled per workspace. Disabled skills are excluded from system prompt injection, activate_skill tool, agent form skill picker, and `/workspace share` export.
 - Selection uses a composite `id:scope` key (localStorage `halo_skills_selectedKey`) so the same id in different scopes can coexist
 
 ### Auto-sync behaviour (workspace vs. global)
@@ -73,13 +73,13 @@ Review the code for:
 
 - **Frontmatter** (required): `name` (kebab-case, = directory name) + `description` — injected into the agent system prompt for discovery
 - **Body**: the full instructions, lazily loaded by the agent via `activate_skill`
-- **Optional fields**: `allowed-tools` (space-separated), `metadata` (custom kv), `command` (slash command registration — opt-in, only declared commands exist), `requiresAccess` (one of `full` / `workspace` / `readonly`), `verbs` (Halo extension — subcommand list, each `{ name, builtin?, requiresAccess?, desc? }`; skill verbs' access gates are declared here), `disable-model-invocation` (standard — command exists but skill is not injected for model auto-activation), `user-invocable` (standard — `false` = never a slash command, model can still activate)
+- **Optional fields**: `command` (slash command registration — opt-in, only declared commands exist), `requiresAccess` (one of `full` / `workspace` / `readonly`), `verbs` (Halo extension — subcommand list, each `{ name, builtin?, requiresAccess?, desc? }`; skill verbs' access gates are declared here), `disable-model-invocation` (standard — command exists but skill is not injected for model auto-activation), `user-invocable` (standard — `false` = never a slash command, model can still activate). Other standard fields (`allowed-tools`, `metadata`) are tolerated but not read
 - **Arguments**: user command-line args fill `$ARGUMENTS` / `$1`–`$9` placeholders in the body (quotes respected, `\$` escapes, `$5.00`/`$PATH` untouched); `{{...}}` placeholders (params/channel/workspace_root etc.) carry platform-injected values — the two coexist without cross-translation. A verb reaches the body as `$1` for dispatch; args are no longer appended verbatim to the body end
 
 ### Skill-as-command
 When a `command` field is present (e.g. `command: /review`), the skill auto-registers as a slash command. Users trigger it with `/review`. See [commands](command.md).
 
-If the `command` collides with a built-in slash command (or another skill's `command`), it is dropped from the command list with a warning — built-ins win, then first-come among skills. Only the slash command is lost; the skill stays usable via `activate_skill`. See [conflict detection](command.md#conflict-detection).
+If the `command` collides with a built-in slash command (or another skill's `command`), it is dropped from the command list (a warning is logged when another skill owns the name) — built-ins win, then first-come among skills. Only the slash command is lost; the skill stays usable via `activate_skill`. See [conflict detection](command.md#conflict-detection).
 
 ### Access-level gate (`requiresAccess`)
 

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

@@ -19,7 +19,7 @@ The Source Control **activity-bar entry itself is hidden in non-git workspaces**
 Once the entry is shown, the panel resolves to one of these on open, driven by `GET /api/git/status`:
 
 1. **Not a repo** (`{isRepo: false}`) — the folder has no git work-tree at its root (either no repo at all, or it only sits *inside* an ancestor's repo). Shows an **Initialize Repository** empty state. Never a 500/console error — a non-repo folder is a normal state.
-2. **Repo, no remote** — `GET /api/git/remotes` is empty. Shows an **Add Remote** prompt to guide first publish. Adding a remote is a purely local op with **no commit precondition** — a freshly-`init`'d empty repo can set its remote URL right away (not gated behind "must have a commit first", which would be a mis-applied VSCode *Publish* gate).
+2. **Repo, no remote** — `GET /api/git/remotes` is empty. The Changes view shows an **Add Remote** prompt (push/pull buttons hidden) to guide first publish. Adding a remote is a purely local op with **no commit precondition** — a freshly-`init`'d empty repo can set its remote URL right away (not gated behind "must have a commit first", which would be a mis-applied VSCode *Publish* gate).
 3. **Repo with remote** — the full panel: CHANGES list, commit box, history graph.
 
 ### Ancestor-repo guard
@@ -30,7 +30,7 @@ A workspace placed *under* another repo (e.g. a dotfiles `$HOME`, or a monorepo
 - CHANGES section lists every modified/added/deleted/untracked/renamed file, split into **Staged** and **Changes** groups (mirrors the porcelain X/Y status chars).
 - Each row shows a VSCode-style status badge: **M** modified (blue), **A** added / **U** untracked (green), **D** deleted (red), **R** renamed / **C** copied (blue), **U→Conflict** unmerged (red).
 - Stage / unstage individual files or all at once (`POST /api/git/stage` · `unstage`).
-- Click a file → opens a **Monaco side-by-side diff** (`GET /api/git/diff`); original side is HEAD (or the rename's old path), modified side is the working/staged copy. Binary files show git's "Binary files differ" rather than crashing.
+- Click a file → opens a **Monaco side-by-side diff** (`GET /api/git/diff`); original side is HEAD (or the rename's old path), modified side is the working/staged copy. There is no binary special case: both sides are read as UTF-8 text (`git show` / the working-tree file), so a binary file opens as garbled text rather than a "Binary files differ" notice.
 - **Single-file discard is intentionally omitted** — it's an "operation", not a "view". Use the command line (`git checkout`).
 
 ## Commit & sync
@@ -39,6 +39,7 @@ A workspace placed *under* another repo (e.g. a dotfiles `$HOME`, or a monorepo
 - **Push** (`POST /api/git/push`): first push of an untracked branch sets upstream automatically (`-u origin <branch>`).
 - **Push failure is surfaced as a friendly red banner**, never a raw leak. A missing-credentials push (`fatal: could not read Username for 'https://...'`) is detected and rephrased into a "configure credentials" guide rather than dumping git's stderr.
 - Pull (`POST /api/git/pull`).
+- The branch row shows the current branch plus **ahead / behind** counts against its upstream (↑N / ↓N, from `GET /api/git/status`; hidden when both are 0), next to the Pull / Push buttons (shown only once a remote exists).
 
 ## Auto-refresh (no polling)
 
@@ -80,4 +81,4 @@ The file tree colors and badges files by git status (VSCode-style), driven by th
 
 ## Out of scope (this round)
 
-Branch create / switch / merge, ahead/behind indicator, AI-generated commit messages, clone, merge-conflict resolution UI, stash, worktree, timeline, PR management, the **DAG rail graph** (branch fork/merge visualization), and single-file discard. The DAG graph + ahead/behind are deferred to the branch-operations round, where they have live branch actions to feed them — standalone they're decoration, not a viewing need.
+Branch create / switch / merge, AI-generated commit messages, clone, merge-conflict resolution UI, stash, worktree, timeline, PR management, the **DAG rail graph** (branch fork/merge visualization), and single-file discard. The DAG graph is deferred to the branch-operations round, where it has live branch actions to feed it — standalone it's decoration, not a viewing need.

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