@turmind/halo 1.6.0 → 1.6.1

package/bundled-docs/dev/deploy.md

@@ -14,6 +14,7 @@ For this host's `/usr` installation and `ubuntu` service user, after authorizati
 (
 set -e
 version='x.y.z'  # exact requested version
+curl -sfI "https://registry.npmjs.org/@turmind/halo/-/halo-$version.tgz" >/dev/null  # tarball replicated? (a fresh publish can 404 for ~15 min)
 sudo sh -c 'umask 022; npm install -g --prefix /usr --no-audit --no-fund "@turmind/halo@$1"' sh "$version"
 installed=$(sudo -u ubuntu env HOME=/home/ubuntu /usr/bin/halo --version 2>&1)
 test "$installed" = "halo $version"  # CLI writes to stderr; mismatch or launch failure stops before restart
@@ -23,6 +24,8 @@ sudo journalctl -u halo.service --since '2 minutes ago' -n 40 --no-pager
 )
 ```
 
+**Fresh-publish gate:** right after `npm publish`, `npm view` may already show the version while the tarball still 404s for several minutes (1.6.0: ~15 min, the first prod install failed `E404` before restart). The `curl -sfI` line stops the sequence before install; wait and rerun, never republish.
+
 **Permission gate:** root npm installs must use `umask 022`, then pass `halo --version` as the actual service user. Secrets/logs can use 077, but it must not leak into public package installation: the 1.5.0-alpha install inherited 077, made root-only package directories and left the ubuntu service failing with 203/EXEC.
 
 **Public release is a separate requested target:** synchronize the five package versions/tag, build and publish npm once, create the GitHub release and attach the Windows exe; verify the exact npm version/dist-tag and GitHub asset. macOS dmg remains the user's step unless requested. See the [publication command reference](#public-release-command-reference) only for the needed commands.

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

@@ -405,17 +405,23 @@ Still good practice: build server + admin **before** `pnpm dist:arm64`.
   confirm does nothing, because `if (!confirm(...)) return` always returns). In
   a plain browser the helpers fall back to the native sync dialogs.
 
+- **macOS notifications need a code-signed app (Electron 42+).** Electron moved
+  to `UNNotification`, which shows nothing for an unsigned app; our dmg is
+  ad-hoc (`identity: null`), so `Notification` emits `failed` (logged as
+  `notification failed: …` in `desktop.log`) and only the Dock bounce remains.
+  The fix is a Developer ID signature, not code.
+
 - **Media capture for extensions (`media` capability, e.g. htrans) —
   ⚠ not yet verified on a real Mac.** Three pieces, all needed:
   - **Info.plist usage strings** (`electron-builder.yml` → `mac.extendInfo`):
     `NSCameraUsageDescription`, `NSMicrophoneUsageDescription`, and
     `NSAudioCaptureUsageDescription` (system-audio capture; required on macOS
     14.2+). Missing ones make macOS deny / kill the request silently.
-  - **`--enable-features=MacLoopbackAudioForScreenShare,MacSckSystemAudioLoopbackOverride`**
-    on macOS (`main.cjs`, appended before app `ready`, merged with any existing
-    `enable-features` value) — Chromium's loopback (system-audio) capture is
-    behind these flags; macOS 13+ (Darwin 22+) only, so older macOS never
-    offers or passes `audio:'loopback'`.
+  - **No feature switch for system audio** (Electron 39+): loopback capture is
+    built in (CoreAudio Tap on macOS 14.2+, ScreenCaptureKit below). The old
+    `MacLoopbackAudioForScreenShare` / `MacSckSystemAudioLoopbackOverride`
+    switches were removed with the Electron 44 upgrade; the plist string above
+    is what still matters.
   - **`getDisplayMedia()` picker**: Electron has no built-in one (the call just
     fails), so `session.setDisplayMediaRequestHandler` (mac / win only; Linux
     keeps Electron's default) lists `desktopCapturer` sources and asks the

package/bundled-docs/dev/env.md

@@ -136,7 +136,7 @@ settings.yaml only (no env override):
 - `general.sandbox.writable_dirs` (default empty) — dirs writable inside the sandbox besides the workspace (Linux / macOS), for external CLIs that keep local state (e.g. `~/.kiro`); not applied to readonly sessions, scope: global
 - `general.sandbox.hidden_files` (default empty) — extra files hidden from workspace/readonly sessions, read as empty files (bwrap bind of `~/.halo/.sandbox-empty` on Linux, Seatbelt deny on macOS), **appended** to the built-in list, which is always included (`~/.npmrc,~/.bash_history,~/.gitconfig,~/.git-credentials,~/.netrc,~/.halo/global/{evo,cron,runs,a2a}.db` + their `-wal`/`-shm` files); Full sessions, the admin file explorer and the terminal are not affected, scope: global
 - `general.logging.level` (default `warn`) — log level: debug | info | warn | error, restart required
-- `general.observability.endpoint` (default `''`) — OTLP collector base URL (e.g. `http://localhost:4318`); empty = off, scope: global, restart required. See [design/observability.md](../design/observability.md)
+- `general.observability.endpoint` (default `''`) — OTLP collector base URL (e.g. `http://localhost:4318`); empty = off, scope: global, restart required (the server; `halo cli` / `halo tui` read all `general.observability.*` keys at start, so cron and evolution runs pick a change up on their next run). See [design/observability.md](../design/observability.md)
 - `general.observability.service_name` (default `halo`) — OTel resource `service.name`, scope: global, restart required
 - `general.observability.headers` (default `''`, secret) — extra OTLP request headers, comma-separated `k=v`, scope: global, restart required
 - `general.observability.capture_content` (default `false`) — put prompt/completion/tool text on spans, scope: global, restart required

package/bundled-docs/dev/previews.md

@@ -25,6 +25,8 @@ previews/
 │   │                         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)
+│   ├── image-annotator.tsx   ImageAnnotator: drawing board over an image → `halo:attach-image`
+│   ├── annotate.ts           Its pure parts: coordinate mapping, strokes reducer, composite
 │   └── print.ts              Pop-up print helper
 ├── workers/                  Parse workers (one per heavy format)
 │   ├── worker-client.ts      Generic WorkerClient<T> class — id-routed postMessage
@@ -68,9 +70,15 @@ interface PreviewProps {
   onOpenAsText?: () => void  // set when the file can also be force-opened as text
   tooLarge?: boolean   // file over the editor's 10MB read cap; FilePreview shows a placeholder instead of the plugin
   size?: number        // on-disk size in bytes, shown by that placeholder
+  mtime?: number       // on-disk mtime the buffer knows — see Live refresh below
+  bundle?: boolean     // `path` is a bundle directory: only bundle extensions are candidates
 }
 ```
 
+### Live refresh
+
+When the open file changes on disk (mtime strictly newer than the buffer's), `FilePreview` remounts a built-in plugin — `key={mtime}`, with `viewUrl` cache-busted (`&v=<mtime>`, `versionedUrl()` in `features/editor/file-refresh.ts`). A plugin needs no code for this, but **all its state resets**: fetched data, zoom, page, selection. Keep anything that must survive outside the component. Extensions aren't remounted — the host re-fetches the file and hands it to the running iframe (skipped while the document is dirty); bundles are left alone.
+
 ## Adding a new file type
 
 ### 1. Create the view component
@@ -171,6 +179,24 @@ Plugin-specific buttons use the shared `<ToolbarButton>`:
 </ToolbarButton>
 ```
 
+## Reusable: `ImageAnnotator` + `halo:attach-image`
+
+`ui/image-annotator.tsx` is the board behind the image preview's **Annotate** button (media-view is the only user today); any preview that shows a picture can mount it.
+
+```tsx
+<ImageAnnotator
+  src={viewUrl}                 // same URL as the <img>
+  name={name}                   // → `<name>-annotated.png`
+  viewStyle={{ transform }}     // the picture's own zoom / pan transform, so marks line up
+  panning={dragging}            // optional: grabbing cursor while the host pans
+  onClose={stopAnnotating}      // Esc, ✕, and after a successful Send
+/>
+```
+
+- Strokes are kept in natural image pixels, mapped through the board's `getBoundingClientRect()`, so any CSS transform on `viewStyle` works. Left / touch drag draws (and swallows the event); everything else — wheel, middle-drag — is left to the host.
+- Send composites image + marks on a canvas (long edge ≤ 4096, `COMPOSITE_MAX_EDGE` in `ui/annotate.ts`) and fires `window.dispatchEvent(new CustomEvent('halo:attach-image', { detail: { file: File } }))`. The chat input (`features/chat/message-input.tsx`) listens: vision model → normal attachment path; text-only → the `chat.attachNoVision` notice; then it shows the chat and focuses the input. Any other feature can hand an image to chat through the same event.
+- Mount it only where the chat is reachable: media-view gates it to the main editor store (Skills / Agents editors scope their own and hide the chat) and skips SVG.
+
 ## Workers — parsing off the main thread
 
 If your format needs CPU-heavy parsing (non-trivial ArrayBuffer → structured data), run it in a Web Worker so the UI stays responsive even with several tabs parsing concurrently.

package/bundled-docs/guide/agents.md

@@ -44,7 +44,7 @@ Data-driven form for name / description / model / tools / skills / thinking. Cha
 **Model section** has four fields:
 - `provider` — dropdown populated from `~/.halo/global/models/*.yaml` plus hub-installed `~/.halo/global/models.d/*.yaml` (`/extension models`; updates the list live)
 - `id` — combobox (input + datalist); preset options filtered by current provider, also accepts manual input of any model ID
-- `endpoint` — combobox (input + datalist); full endpoint URL (e.g. `https://bedrock-runtime.ap-northeast-1.amazonaws.com`), supports custom proxy URLs
+- `endpoint` — combobox (input + datalist); full endpoint URL (e.g. `https://bedrock-runtime.ap-northeast-1.amazonaws.com`), supports custom proxy URLs. When a model is only served in some regions the list narrows to those, switching to it moves the endpoint there, and an endpoint off its list shows a warning
 - `maxTokens` — optional; defaults to `maxOutputTokens` in the provider yaml
 
 Switching provider resets the model id to the new provider's default model (its `defaultModelId`), keeping the current id when the new provider lists it too.
@@ -141,8 +141,8 @@ priority: 0
 
 model:
   provider: aws-bedrock-claude-invoke       # required, matches ~/.halo/global/models/<provider>.yaml
-  id: global.anthropic.claude-sonnet-4-6   # the provider yaml's defaultModelId
-  endpoint: https://bedrock-runtime.us-west-2.amazonaws.com  # full endpoint URL; supports custom proxy
+  id: global.anthropic.claude-opus-5-5     # any model id the provider lists (or a custom one)
+  endpoint: https://bedrock-runtime.us-east-1.amazonaws.com  # full endpoint URL; supports custom proxy
   maxTokens: 16384                   # optional, max output tokens (default from provider yaml)
 
   # Prompt caching — lower cost on repeated system prompts
@@ -161,8 +161,8 @@ system_prompt: |
 
 # Context window
 context:
-  maxTokens: 272000                  # max context (default 272000)
-  compressAt: 0.9                    # auto-compact trigger (0.9 = compact when 90% full)
+  maxTokens: 272000                  # context budget — new agents get the model's recommended window; can't exceed the model's max
+  compressAt: 0.9                    # auto-compact trigger (0.9 = compact when 90% full); new agents get your global setting, else the model's
 
 # Tool allowlist (strict by name; unlisted tools are not injected).
 # Session/delegation tools are NOT listed here — see `team` below.
@@ -191,7 +191,7 @@ team:
 **Full tool list**: see [dev/tools.md](../dev/tools.md).
 
 **Common edits**:
-- Agent handling long tasks → `context.maxTokens: 500000` + `context.compressAt: 0.85`
+- Agent handling long tasks → raise `context.maxTokens` up to the model's max (the form shows it, e.g. 1M for Opus 5.5) + `context.compressAt: 0.85` — on most 1M-class models input past 272K bills at long-context rates
 - Save cost → `model.promptCaching: '1h'`
 - Complex reasoning → `thinking.enabled: true` + `thinking.effort: high`
 - Read-only agent → keep only `file_read` / `file_list` / `grep` / `glob` in `tools`

package/bundled-docs/guide/cli.md

@@ -64,8 +64,9 @@ To list agents or sessions without running a prompt, use the dedicated subcomman
 | Flag | Short | Default | Description |
 |---|---|---|---|
 | `--workspace` | `-w` | cwd | Workspace path |
-| `--agent` | `-a` | `default` | Agent ID |
-| `--session` | `-s` | auto | Resume session by ID |
+| `--dir` | | root | Focus the session on a workspace sub-folder — same as a sub-agent's `working_dir`: the folder's `.halo/INSTRUCTIONS.md` chain joins the system prompt, plus a `Working directory:` line. Workspace-relative or absolute; must exist inside the workspace. On a resumed session it re-points the stored folder in place (one `[cli] session <id>: dir <from> → <to>` line on stderr); `--dir .` moves it back to the root |
+| `--agent` | `-a` | `default` | Agent ID. A session's agent never changes: `-s <existing>` with a different `-a` is refused (`session <id> runs agent <x>; omit -a to resume it, or use -n …`); without `-s`, the latest cli session is only resumed when it runs the `-a` agent — otherwise a new session starts |
+| `--session` | `-s` | auto | Resume session by ID; created with that id when it doesn't exist |
 | `--new` | `-n` | off | Always start a new session |
 | `--format` | `-f` | `text` | Output format: `text` or `json` |
 | `--verbose` | `-v` | off | Show thinking, tool calls, usage on stderr |
@@ -129,7 +130,7 @@ Multi-turn conversation. Supports all standard Halo slash commands:
 | Command | Description |
 |---|---|
 | `/help` | Show available commands |
-| `/session new` | Start a new session |
+| `/session new` | Start a new session — it keeps the current session's folder (`--dir`; from a sub-agent, its root's), or starts at the root if that folder is gone |
 | `/session list` | List recent sessions |
 | `/session switch <n>` | Switch to session by number |
 | `/session stop` | Stop current agent task (ends the turn, no re-run) |
@@ -227,7 +228,7 @@ halo models install <dir> [--yes]   # install <dir>/*.yaml into ~/.halo/global/m
 halo models list                    # id · copy in effect (bundled | hub) · revision · runtime
 ```
 
-Normally run for you by `/extension models`, which downloads the hub's newest `models-v*` release (https GitHub / Gitea / Forgejo / GitLab only) and passes the unpacked directory to `halo models install`. Per provider id the copy with the higher `revision` is in effect (tie → the `models.d` copy); an older one is skipped, an identical one reported up to date. Refused per provider: a `runtime:` this halo doesn't know (needs a newer halo), no `revision`, a `secrets[].default` that isn't empty or `<<ENV_NAME>>`. If any provider is new or changes `defaultEndpoint` / `endpointPresets`, the changes are listed, **nothing is written**, and the exit code is `3` — re-run with `--yes` to apply. Writes are atomic (tmp + rename); a running server reloads its registry from `models.d/` without a restart and pushes the change to open admin pages. Existing agents keep the model / endpoint in their own `agent.yaml`. Exit codes: `0` ok (refusals listed in the summary line), `1` error, `3` needs `--yes`. To undo, delete the file from `~/.halo/global/models.d/`.
+Normally run for you by `/extension models`, which downloads the hub's newest `models-v*` release (https GitHub / Gitea / Forgejo / GitLab only) and passes the unpacked directory to `halo models install`. Per provider id the copy with the higher `revision` is in effect (tie → the `models.d` copy); an older one is skipped, an identical one reported up to date. Refused per provider: a `runtime:` this halo doesn't know (needs a newer halo), no `revision`, a `secrets[].default` that isn't empty or `<<ENV_NAME>>`. Endpoint changes against the copy in effect are always listed. Consent is needed for any URL the server would now send requests (and credentials) to that it didn't before: a new provider, a changed `defaultEndpoint` / `endpointPresets`, or a URL added to a model's `endpoints:` list that the provider doesn't already use anywhere. A model list that only loses URLs, or gains one already used elsewhere in the provider, is listed but needs no consent; a reorder alone is not a change. When consent is needed, **nothing is written** and the exit code is `3` — re-run with `--yes` to apply. Writes are atomic (tmp + rename); a running server reloads its registry from `models.d/` without a restart and pushes the change to open admin pages. Existing agents keep the model / endpoint in their own `agent.yaml`. Exit codes: `0` ok (refusals listed in the summary line), `1` error, `3` needs `--yes`. To undo, delete the file from `~/.halo/global/models.d/`.
 
 ## Server Mode (background daemon)
 

package/bundled-docs/guide/skills.md

@@ -26,9 +26,15 @@ Putting those in AGENT.md would bloat the system prompt. Skills use **progressiv
   deploy-check/
     SKILL.md
     scripts/verify.sh
+
+~/.halo/global/extensions/<ext>/skills/   # Shipped by an installed extension (read-only)
+  <ext>-helper/
+    SKILL.md
 ```
 
-Workspace overrides global (same id).
+Precedence for the same id: workspace > global > extension. The higher folder wins wholly.
+
+**Extension skills** come with an installed canvas extension (see [Canvas preview extensions](../design/canvas-extensions.md#extension-skills)). They appear in the Skills panel under **Extensions** ("from extension X"), read-only: no edit, no delete. They are not enabled automatically: tick them for an agent like any other skill. Uninstalling the extension removes them. To customise one, copy its folder into `~/.halo/global/skills/<id>/` or `<project>/.halo/skills/<id>/` and edit the copy, which then takes precedence.
 
 **Built-in skills** (`agent`, `skill`, `workspace`, `cron`, `send-file`, `self`, `aws-knowledge`, `web-search`, `halo`, `extension`) are server-shipped and **force-overwritten on every server startup**. Local edits to these directories under `~/.halo/global/skills/` will be lost. To customize one, copy it into `<project>/.halo/skills/<id>/` (workspace replaces global) and edit there. Other skills under `~/.halo/global/skills/` — including any the user created via the admin UI — are untouched by the seeder.
 
@@ -75,7 +81,7 @@ You can edit SKILL.md, add scripts, templates, example docs.
 
 Click the `+` on the **Global** or **Workspace** group header in the sidebar (the group you click decides the scope) and type a name.
 
-Delete: hover a skill and click its trash icon (after a confirmation). The toggle next to it disables / enables the skill.
+Delete: hover a skill and click its trash icon (after a confirmation). The toggle next to it disables / enables the skill. The **Extensions** group has no `+` and no trash. Its skills go away when the extension is uninstalled, but the toggle works.
 
 ## Letting an agent use a skill
 
@@ -113,10 +119,10 @@ The agent follows the skill's instructions.
 
 ## Resource files
 
-Files in the same directory as SKILL.md are listed at the end of `activate_skill`'s return:
+Files in the same directory as SKILL.md are listed at the end of `activate_skill`'s return, under the skill directory's absolute path:
 
 ```
-Resource files in skill directory:
+Resource files in skill directory (/home/me/.halo/global/skills/code-review):
 - checklist.md
 - examples/review-sample.md
 ```
@@ -161,7 +167,7 @@ Halo seeds these skills on every startup (the ids in `BUILTIN_SKILL_IDS`, `packa
 | halo | Platform self-knowledge — config directories, MD scopes, which bundled doc answers what (no command, `user-invocable: false`; model auto-activates) |
 | extension | Install / list / remove canvas preview extensions — backs `/extension` (full access); its `hub_repo` param (Settings → Skills) picks the hub `install <id>` pulls from (default turmind/halo-hub) |
 
-All live under `~/.halo/global/skills/` and are force-overwritten on startup. To customize one, copy it into `<project>/.halo/skills/<id>/` and edit there (workspace overrides global). `tavily-web-search` remains an optional (non-seeded) skill.
+All live under `~/.halo/global/skills/` and are force-overwritten on startup. To customize one, copy it into `<project>/.halo/skills/<id>/` and edit there (workspace > global > extension). `tavily-web-search` remains an optional (non-seeded) skill.
 
 ## SKILL.md field reference
 
@@ -206,7 +212,7 @@ user-invocable: false                # optional (standard), never becomes a slas
 
 {body}
 
-Resource files in skill directory:
+Resource files in skill directory (<absolute skill dir>):
 - checklist.md
 - examples/review.md
 ...

package/bundled-docs/guide/workspace.md

@@ -124,7 +124,7 @@ Common settings:
 - `general.session.max_nesting_depth` — max session nesting depth
 - `general.compact.keep_messages` — recent messages kept intact during compaction
 - `general.logging.level` — `debug` / `info` / `warn` / `error`
-- `general.observability.endpoint` — OTLP collector URL; leave empty to keep observability off (see [design/observability.md](../design/observability.md))
+- `general.observability.endpoint` — OTLP collector URL; leave empty to keep observability off. The server and every `halo cli` / `halo tui` run (cron and evolution runs included) export to it (see [design/observability.md](../design/observability.md))
 - `<provider-id>.secrets.api_key` — provider credentials (Kimi / DeepSeek bearer token)
 - `<provider-id>.secrets.access_key_id` / `.secret_access_key` — AWS Bedrock
 - `<skill-id>.params.<key>` — values an agent can inject into its own `shell_exec` via `{{<skill-id>.params.<key>}}`

package/bundled-docs/requirements/agent.md

@@ -22,6 +22,11 @@ Left sidebar has two collapsible groups (Global / Workspace — the latter only
 
 ### Form / Edit dual view
 - **Form view** (default): data-driven form derived from the YAML fields (name / description / priority / model incl. thinking and capabilities / system_prompt / team / tools / skills). Edits auto-save to `agent.yaml` (debounced 500 ms). If `agent.yaml` fails to load or parse, the form is replaced by an error with a Retry button and nothing is auto-saved (an unparsable file is fixed in Edit view); below the form, a read-only preview of `AGENT.md` is shown when it has content
+- **Model / context fields** in the form:
+  - **Endpoint list**: the dropdown offers the model's own `endpoints:` when the registry declares them, else the provider's `endpointPresets`; free text stays allowed.
+  - **Auto-switch on model change**: switching to a model with its own list moves the endpoint to that model's default when the current one (or, left empty, the provider default) isn't on the list, with a one-line note naming the new endpoint; a model without a list leaves the endpoint alone. Switching provider sets the new model's default endpoint.
+  - **Off-list warning**: a saved / typed endpoint outside the model's own list shows an amber "not listed on this endpoint — requests may fail" hint (not blocked).
+  - **Context**: switching model moves `context.maxTokens` / `compressAt` to the new model's recommended values when the old ones were the old model's untouched recommendation (or the window exceeds the new model's max); hand-set values that still fit are kept. The `context.maxTokens` input shows "Model max N" (the registry `maxContextWindow`); an over-max draft turns red ("Exceeds model max N — not saved") and is never auto-saved, and the server refuses it too (400), except a value already on disk for the same model. An empty or non-positive draft is ignored — the saved value stays.
 - **Edit view**: the **Edit** button opens a mini workspace (file tree + editor) rooted at the agent's folder, for editing `agent.yaml` / `AGENT.md` directly; **Back** returns to the form, which reloads from disk
 - The chosen view is remembered per agent in `localStorage`
 

package/bundled-docs/requirements/chat.md

@@ -60,11 +60,12 @@ The workspace's root sessions as **Chrome-style vertical tabs** on the right edg
 - **Rows**: one line per row — just the title, no leading icon cell (the "New session" draft row has none either, so the titles line up). Message count, time-ago, model and the state text (`Working…` / `New messages` / `Idle`) are in the tooltip, the state after a ` · ` at the end of its second line. `N msgs` counts the session's user turns **over its whole lifetime**, so compacting or archiving history never makes it go backwards.
   - Each row carries a **2px status bar** along its bottom edge, full row width with 6px inset on both sides and rounded ends (absolutely positioned, so a state change never reflows a narrow list — the spinner it replaced did; decorative, `aria-hidden`): **amber, breathing** (`animate-pulse`) while a loaded tab's turn is running; **blue**, solid, when a loaded background tab is idle with unread output (output landed while it wasn't on screen; cleared when shown); **green** otherwise — including sessions no tab has loaded and tabs a reconnect released. Green is the norm, so it is **dimmed** (`/40`) to recede into the background, and rises to `/70` on the selected and hovered row; amber and blue never dim. The list endpoint's `status` is not used. In the light and warm themes amber renders as the theme's darker orange, same as the rest of the UI.
   - Infinite scroll pages older sessions. A "+" footer starts a new session.
-- **Hover peek (collapsed list)**: resting the mouse on the collapsed rail for 300 ms slides the **full list** (header + rows) in over the chat to its left, at the saved width, without reflowing the chat; leaving closes it after a 200 ms grace. Touch never opens it. It stays open while a rename input or the delete confirm started from it is in progress, and selecting a row closes it. Collapsing by mouse click does not peek straight back open under the pointer until it leaves and re-enters; the peek header's expand button pins the list open.
+- **Hover peek (collapsed list)**: resting the mouse on the collapsed rail for 300 ms slides the **full list** (header + rows) in over the chat to its left, at the saved width, without reflowing the chat; leaving closes it after a 200 ms grace. Touch never opens it. It stays open while the row menu, a rename input or the delete confirm started from it is open, and selecting a row closes it. Collapsing by mouse click does not peek straight back open under the pointer until it leaves and re-enters; the peek header's expand button pins the list open.
 - **New session**: "+", `/session new` and `/clear` open a **draft tab**. A "New session" row sits on top while it is on screen, and an untouched draft is reused rather than duplicated. The session is created by the draft's first message or command. The previous session keeps streaming in its own tab.
 - **Background tabs**: one WS connection carries every loaded tab, so a session that isn't on screen keeps receiving its turn. After a reconnect only the tab on screen is reattached; the others reload when clicked. Live capture and face (`<<<SHOW>>>`) markers only act for the tab on screen.
-- **Delete (trash icon)**: deletes the session after a confirm dialog in the UI language ("Delete this session? Its history cannot be recovered." / its Chinese counterpart). Deletion is the REST delete first, then the WS one, so sub-session files go too. The trash icon, like the **rename** pencil, appears only on hover — the active tab included.
-- **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
+- **Row menu (Rename / Delete)**: rows carry no hover buttons. Right-click a row (long-press ~500 ms on touch; moving or lifting early cancels) to open a menu at the pointer with **Rename** (inline rename) and **Delete session** (red). Esc or a click outside closes it. The draft row and the collapsed squares have no menu.
+- **Delete**: deletes the session after a confirm dialog in the UI language ("Delete this session? Its history cannot be recovered." / its Chinese counterpart). Deletion is the REST delete first, then the WS one, so sub-session files go too.
+- **Inline rename**: menu → 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
 - **Persistence**: only the session on screen is remembered, per workspace, as `{active}` under `halo_chat_tabs_<projectId>`. A refresh restores and loads only that tab. The pre-tabs keys `halo_session_<projectId>` / `halo_session_id` are read once to seed it and then removed.
 - **Switch loading**: clicking a row that hasn't loaded yet shows 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. Switching to an already-loaded tab is instant, and its scroll position is restored
 
@@ -100,6 +101,9 @@ When `contextEnabled` is on (default), user messages are auto-prepended with:
 - Clipboard paste
 - File-picker button
 - Screenshot button (below)
+- Canvas image **Annotate → Send to chat** (`<name>-annotated.png`; see `requirements/editor.md` → Image annotation)
+
+On an agent whose model has no image input, an annotated image is not attached — the attachment-notice row says the model doesn't take images (`chat.attachNoVision`).
 
 Images ride along as base64; multimodal supported. Before sending, every attachment is downscaled (long edge ≤ 1568) and re-encoded as JPEG; an SVG is rasterized the same way (long edge 1024, on white), since vision input only takes jpeg / png / gif / webp. An image the browser can't decode (e.g. HEIC / TIFF in Chrome) and that isn't one of those four is refused when attached, with an inline notice naming the file — it is never sent only to be dropped server-side. Pasted images are also persisted to `<workspace>/.halo/assets/web/inbound/web/<date>/` so a `[图片已保存: /abs/path]` marker survives page reload and renders as a click-to-preview chip (shared with the WeChat channel's inbound media flow).
 

package/bundled-docs/requirements/command.md

@@ -25,6 +25,10 @@ The rest are noun-verb **object commands**: `/<obj> <verb> [args]`. Some verbs a
 
 Session lifecycle actions (`subscribe` / `unsubscribe`, `session:delete`) are handled inline by the WS handler, not as slash commands. In the admin, a bare `/session new` (and `/clear`) is handled client-side: it opens a new draft chat tab and sends nothing; `/session new <args>` still goes to the server. The WS `session:clear` frame was removed in 1.5.3-alpha.
 
+### `/session new`
+
+Built-in verb, all users. Creates a new root session with the workspace's entry agent and switches the caller to it. The new session **keeps the current session's folder** (its `working_dir`, e.g. from `halo tui --dir sub`): from a sub-agent, its root's folder. The folder is re-checked; if it no longer exists, the new session starts at the workspace root.
+
 ### `/session info`
 
 Built-in verb (no access gate beyond ownership). Prints the **session tree** for the caller's current root session — the root plus every descendant sub-agent, so the user can see the whole delegation fan-out at a glance:

package/bundled-docs/requirements/editor.md

@@ -26,10 +26,15 @@ Monaco-based multi-tab code editor + binary file previewer — surfaced in the U
 - Server returns the new `modifiedAt`; the tab updates its mtime
 
 ### Auto-refresh (mtime-based)
-When agents write files through tools, the canvas detects it — push-based, no polling:
-1. The server's WS `file:changed` (`change`) event re-reads the matching open tab; the active tab is also re-checked with `GET /api/files/stat` on tab switch, window focus and WS reconnect
-2. If `diskMtime > tab.mtime`, pull fresh content
-3. Skip if the user has unsaved edits (don't overwrite)
+When agents or scripts write files, the canvas picks it up — push-based, no polling:
+1. A WS `file:changed` `change` **or `add`** event (`add` = a file renamed over the open one, e.g. `sed -i` or a tmp-file replace) refreshes every open buffer of that path, in all panes. Tab switch, window focus and WS reconnect re-check only the focused pane's active tab (`GET /api/files/stat`)
+2. Only a disk mtime strictly newer than the buffer's counts
+3. Text tab: pull fresh content — skipped if the user has unsaved edits (don't overwrite)
+4. Built-in preview: remounts with a versioned URL (fresh fetch / parse, no stale browser copy), so its view state (zoom, page, annotation marks) resets. Extension preview: not remounted — its host reloads the file inside the running extension (see *Editable extensions*). Bundle directories are skipped
+5. HTML preview: reloads only when the `.html` file itself changes and its text tab has no unsaved edits; changes to linked CSS / JS / images don't trigger it
+6. The pinned face (`self.html`) is excluded — a reload would reset it
+
+With no session selected no `file:changed` arrives (the WS subscribes on session select), so only the tab-switch / focus / reconnect checks apply.
 
 ### Tab persistence
 Open tabs and the active tab live in localStorage; survive refresh.
@@ -47,7 +52,7 @@ Non-text files go through `FilePreview`, which looks up a **plugin** in the prev
 - **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** — `<img>` (via `SafeImage`: pulsing placeholder while loading, "Image unavailable" box on failure, never the broken-image icon; zoom / pan unchanged) / native `<video>` / `<audio>`, supports HTTP Range for seek-without-full-download. Markdown-preview images use the same placeholder.
+- **Images / video / audio** — `<img>` (via `SafeImage`: pulsing placeholder while loading, "Image unavailable" box on failure, never the broken-image icon; wheel / toolbar zoom, left- or middle-drag pan, reset; **Annotate** — below) / native `<video>` / `<audio>`, supports HTTP Range for seek-without-full-download. Markdown-preview images use the same placeholder.
 
 All previews share a **standard header** (`PreviewShell`) with filename, Download, Open-as-Text, and an `extraToolbar` slot for plugin-specific buttons (e.g. DOCX Print, XLSX sheet tabs).
 
@@ -55,6 +60,14 @@ Fetched via `GET /api/files/download?inline=1` (supports Range, streams on the s
 
 Adding new file types is a plugin concern — see `dev/previews.md` for the extension guide.
 
+### Image annotation
+An image preview's toolbar has **Annotate**: a drawing board over the picture to mark it up and send it to the agent. Offered only once the image has loaded, not for SVG (may have no intrinsic size), and only in the main Canvas — not the Skills / Agents editors, whose chat is hidden.
+- Tools: pen / rectangle / arrow; colours red (default) / yellow / green / blue; undo (also Ctrl/Cmd+Z), clear. Lines are drawn 4 px wide at the current zoom. A flat rectangle or zero-length arrow is dropped
+- Zoom and pan stay live: wheel / toolbar zoom, middle-drag pans (left / touch drag draws). A second finger or a palm while drawing is ignored — it neither pans nor draws
+- **Send to chat** renders the image at full resolution (long edge capped at 4096, marks scaled with it) as `<name>-annotated.png`, attaches it to the chat input like any upload, closes the board and puts the caret in the chat input — un-maximizing Canvas and switching the bottom panel to Chat if needed. On an agent whose model has no image input nothing is attached; the attachment-notice row says so. If rendering fails, an inline error shows and the marks stay
+- **Esc**, ✕ or the Annotate button again exits; while maximized the first Esc only exits annotate. Esc and Ctrl/Cmd+Z don't act while typing in an input / Monaco
+- Marks are never saved: exiting, switching the pane to another tab, or the file changing on disk discards them
+
 ### Preview extensions (installable viewers)
 File types without a built-in plugin can be handled by an **installed extension**: a static HTML bundle under `~/.halo/global/extensions/<id>/` (server-wide, not per workspace) that Canvas loads in a sandboxed iframe (scripts + same-origin, like the HTML preview — an extension is trusted like a skill the user chose to install). Design: `design/canvas-extensions.md`.
 - **Resolution order** for a file extension: `default`-priority extensions (newest install wins) → built-in plugins → `option`-priority extensions. `.glb` with the `glb` extension installed opens in the viewer directly; an `option` extension only shows up in the header's **Open with** menu
@@ -65,6 +78,7 @@ File types without a built-in plugin can be handled by an **installed extension*
 - **Export from an editable extension** (e.g. draw.io *File ▸ Export as*, Excalidraw main menu *Export PNG / SVG*): the extension iframe can't download files, so the exported image is saved **into the workspace, next to the open file** (`flow.drawio` → `flow.png`). If that file already exists the user is asked whether to overwrite it. On success a banner "Exported to <path>" appears above the preview with a **Download** link. Exporting never marks the tab modified and never changes the open file. Only on Halo builds newer than 1.5.9; on older hosts the extension shows no working export (drawio ≥ 1.1.0 / excalidraw ≥ 1.1.0 hide or fall back on their own)
 - **Bundle extensions** (manifest `bundle: true`, e.g. the `htrans` meeting recorder): a *directory* named with the extension's suffix (`Standup.htrans/`) is one document. In the Explorer it shows a package icon; clicking the row (or Enter) opens it as a tab, and only its chevron expands it so the files inside stay browsable. Right-click → Open to the Side works on it. **New File** with a bundle suffix (`Standup.htrans`) creates the directory and opens it — from the file tree's inline New File and from the Explorer header's New File button alike. The extension reads and writes only inside that directory. While it reports busy (e.g. recording) the tab shows the dirty dot, asks before closing, and stays mounted when you switch tabs. Ctrl/Cmd+S / Save do nothing on it. A bundle tab survives a reload while the extension is installed and supported here; otherwise the tab is dropped and the directory is an ordinary folder again
 - **File access beyond the open file** (manifest capability `fs-read`; Settings → Extensions tags it "Reads files on this machine"): a viewer such as an emulator or model viewer may read other files in the workspace or anywhere on the server machine (never write), and ask the user to choose one. The choice is made in a **file picker** the viewer opens on demand: Workspace and Home shortcuts, an editable path box, a breadcrumb, folders first, only files matching the viewer's suffix filter; arrow keys / Enter / Backspace to navigate, Esc or Cancel to close it. A file inside the workspace is handed back as a workspace-relative path, any other as an absolute one. Halo's own secrets (`~/.halo/secrets`, `~/.ssh`, git credentials, the global databases — the same paths the agent sandbox hides) never show up in the picker and can't be read this way, symlinks included
+- **Running notebook cells** (ipynb 2.0.0+ on Halo 1.6.1+): the ipynb viewer edits and saves cells (an editable extension, as above) and runs them on a real kernel on the Halo machine through Halo's Jupyter proxy — any kernelspec the configured Jupyter finds (Python, R, …), started with the notebook's folder as the working directory. Halo starts a local Jupyter server on first use; Jupyter itself is not bundled (`pip install jupyter_server ipykernel`; the viewer shows that hint when it is missing). Same trust as the built-in terminal: the kernel runs as the Halo service user, unsandboxed, and only a logged-in admin can reach it (no web-channel / IM / A2A tokens; not in AgentCore mode). Settings → General: `jupyter.enabled` (allow notebook execution, default on) and `jupyter.path` (full path to `jupyter`, empty = PATH), both applied without a restart. Closing the notebook tab shuts its kernel down after 60 s (a reload within that keeps it); a kernel idle for 1 h is shut down even while the tab is open; stopping Halo stops every kernel. Older hosts don't advertise it: the viewer still edits and saves, without run controls
 - **Platforms** (manifest `platforms`: `web` / `desktop-mac` / `desktop-win` / `desktop-linux`; omitted = everywhere): on an excluded platform (the Halo desktop app is detected by its user agent) the extension acts as if it were not installed. The fallback page says `"<name>" only runs on: <platforms>`, and Settings → Extensions shows a platforms badge plus a gray "not supported here" tag. Manifest capability `media` lets the extension use the microphone and screen capture
 - **Install sources**: Settings → Extensions zip upload; `/extension install <id|zip|url>` (listed by the built-in `default` agent, full access), where an id comes from the hub in Settings → Skills → extension → `hub_repo` (default halo-hub; GitHub / Gitea / Forgejo / GitLab release zips, or tags of any other git repo); or a manual directory drop
 - **Live install / upgrade / uninstall** (from Settings → Extensions upload / remove, the `/extension` skill, or a manual directory change): pushed over WS, no reload. An upgraded extension remounts open tabs (or shows a "updated — reload" banner if the tab is dirty); uninstalling drops clean tabs to the fallback page and keeps dirty tabs alive with a banner
@@ -78,7 +92,7 @@ Markdown and HTML open as text in Monaco *and* have a rendered view — Canvas d
 - Toggle to Edit → Monaco source, Cmd+S saves as usual
 
 ### Preview caching (MRU)
-Recently opened preview tabs stay mounted (up to 5, MRU) so switching between them doesn't re-fetch or re-parse. Plugins flagged `heavy: true` bypass the cache — only the active instance mounts, others unmount; switching between two heavy tabs of the same type (e.g. two `.ipynb`) remounts the viewer, so it shows the newly active file. An extension tab with unsaved edits stays pinned beyond the 5. Cached previews keep a fixed (path-sorted) order in the DOM rather than moving with recency, so switching tabs never reloads an extension iframe — a running emulator keeps its state. Closing a preview tab removes it from the cache immediately (aborting any in-flight fetch).
+Recently opened preview tabs stay mounted (up to 5, MRU) so switching between them doesn't re-fetch or re-parse. Plugins flagged `heavy: true` bypass the cache — only the active instance mounts, others unmount; switching between two heavy tabs of the same type (e.g. two `.glb`) remounts the viewer, so it shows the newly active file. An extension tab with unsaved edits stays pinned beyond the 5. Cached previews keep a fixed (path-sorted) order in the DOM rather than moving with recency, so switching tabs never reloads an extension iframe — a running emulator keeps its state. Closing a preview tab removes it from the cache immediately (aborting any in-flight fetch).
 
 ### File metadata in header
 The Canvas header shows `(size · Created … · Modified …)` for the active tab. Both text tabs and preview tabs populate this — preview tabs fetch `GET /api/files/stat` on open (and on tab restore from localStorage) since they never read content.

package/bundled-docs/requirements/skill.md

@@ -20,17 +20,20 @@ button is hidden in this mode (`showMaximize={false}`).
 
 | Operation | API |
 |---|---|
-| List | `GET /api/skills?projectId=xxx` — returns BOTH global and workspace skills as separate entries (no merge); global entries shadowed by a same-id workspace skill are flagged `overridden: true` |
-| Create | `POST /api/skills` (body: name, description, scope, projectId) |
-| Delete | `DELETE /api/skills/:id?scope=...&projectId=...` |
-| Toggle disabled | `PATCH /api/skills/:id/toggle?scope=...&projectId=...` → `{ ok, disabled }` |
+| List | `GET /api/skills?projectId=xxx` — returns workspace, global AND extension skills as separate entries (no merge); entries shadowed by a higher-precedence same-id skill are flagged `overridden: true`; extension entries carry `extId` |
+| Create | `POST /api/skills` (body: name, description, scope, projectId) — `scope: 'extension'` → 403 |
+| Delete | `DELETE /api/skills/:id?scope=...&projectId=...` — `scope=extension` → 403 |
+| Toggle disabled | `PATCH /api/skills/:id/toggle?scope=...&projectId=...` → `{ ok, disabled }` (all three scopes) |
 
-### Scope (Global / Workspace)
+### Scope (Global / Workspace / Extension)
+
+Runtime precedence for one id: workspace > global > extension. The higher folder wins wholly.
 
 | Scope | Path | Notes |
 |---|---|---|
-| Global | `~/.halo/global/skills/<id>/` | Shared across projects |
-| Workspace | `<project>/.halo/skills/<id>/` | Wins over a same-id global skill at runtime |
+| Global | `~/.halo/global/skills/<id>/` | Shared across projects; wins over a same-id extension skill |
+| Workspace | `<project>/.halo/skills/<id>/` | Wins over a same-id global or extension skill at runtime |
+| Extension | `~/.halo/global/extensions/<extId>/skills/<id>/` | Shipped by an installed extension (valid manifest; id `<extId>` or `<extId>-*`). Read-only; removed with the extension. See [design/canvas-extensions.md → Extension skills](../design/canvas-extensions.md#extension-skills) |
 
 ### Management UI
 
@@ -38,8 +41,9 @@ The Skills sidebar mirrors the Agents sidebar layout:
 - 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
-- 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.
+- Items overridden by a higher-precedence skill are rendered dimmed with "overridden" subtitle
+- A third section, **Extensions** (puzzle icon), is shown only when an installed extension ships skills. It has no + button and no trash button; the toggle stays. The subtitle reads "from extension X". Clicking one opens a read-only file view (badge "from extension · read-only" and a hint to copy the folder into global / workspace) instead of the mini workspace editor
+- 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). Global, workspace and extension skills can each be toggled per workspace (rows keyed `scope:id`, e.g. `extension:<id>`). 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)
@@ -54,6 +58,8 @@ The Skills sidebar and any open mini-workspace editor stay in sync with the file
 
 So when an agent (or the `skill` skill) creates a **global** skill, the Skills sidebar won't reflect it until the user refocuses the browser window. The `skill` skill documents this so agents can warn the user.
 
+Extension skills follow the extension, not a file watcher. Installing or uninstalling an extension broadcasts `extension:changed`, which bumps `skill-bus`, so the sidebar and the agent form's skill picker refetch live. Edits inside an installed extension's `skills/` push nothing (show on focus refresh); reinstalling the extension is how a change ships.
+
 ### SKILL.md protocol
 
 ```markdown