@turmind/halo 1.5.4 → 1.5.5

package/bundled-docs/design/observability.md

@@ -34,14 +34,14 @@ No `OTEL_EXPORTER_OTLP_ENDPOINT` after the mapping → `enabled=false`, `initObs
 
 | module | role |
 |---|---|
-| `packages/server/src/observability/otel.ts` (91 lines) | Bootstrap. `initObservability()` / `shutdownObservability()`, the `enabled` gate, `tracer` / `getMeter()` / `otelLogger` / `captureContent()` exports. |
-| `packages/server/src/observability/otel-sdk.ts` (47 lines) | The ONE module that imports the SDK packages and OTLP exporters. |
-| `packages/server/src/observability/genai-spans.ts` (296 lines) | The span model: `beginTurn` / `onAgentEvent` / `recordRetry` / `endTurn`. |
+| `packages/server/src/observability/otel.ts` | Bootstrap. `initObservability()` / `shutdownObservability()`, the `enabled` gate, `tracer` / `getMeter()` / `otelLogger` / `captureContent()` exports. |
+| `packages/server/src/observability/otel-sdk.ts` | The ONE module that imports the SDK packages and OTLP exporters. |
+| `packages/server/src/observability/genai-spans.ts` | The span model: `beginTurn` / `onAgentEvent` / `recordRetry` / `endTurn`. |
 | `packages/server/src/agents/session-manager.ts` | Calls the four hooks above from the turn loop (see below). |
 | `packages/server/src/logger.ts` | Bridges every `logger.*` call into an OTel LogRecord when `enabled`. |
-| `packages/server/src/index.ts` | `await initObservability()` (L262, before `initLogger()`) and `await shutdownObservability()` (L599, in `gracefulShutdown`). |
+| `packages/server/src/index.ts` | `await initObservability()` (before `initLogger()`) and `await shutdownObservability()` (in `gracefulShutdown`). |
 
-**Hook call sites in `session-manager.ts`**: `beginTurn(session, message)` at L1276 (start of `runAgentTurn`), `onAgentEvent(session, event)` at L1316 (inside the agent event loop, one call per `AgentEvent`), `recordRetry(kind)` at the 7 retry catch sites, `endTurn(session, {error?})` at L1547 (the turn's single exit point, success or failure).
+**Hook call sites in `session-manager.ts`** (all in `runAgentTurn`): `beginTurn(session, message)` at the start, `onAgentEvent(session, event)` inside the agent event loop (one call per `AgentEvent`), `recordRetry(kind)` at the 7 retry catch sites, `endTurn(session, {error?})` once after the retry loop (the turn's single exit point, success or failure).
 
 **The `enabled` gate.** `otel.ts` exports a single `enabled: boolean`, set once by `initObservability()`. Every hook in `genai-spans.ts` and the `logger.ts` bridge checks it first — an unconfigured server pays nothing beyond one boolean read per hook call.
 
@@ -49,9 +49,9 @@ No `OTEL_EXPORTER_OTLP_ENDPOINT` after the mapping → `enabled=false`, `initObs
 
 **Why the meter is lazy.** The `@opentelemetry/api` tracer and logger are proxies — they stay no-op until a real provider is registered, then transparently start forwarding, so `tracer` / `otelLogger` can be module-level consts. The metrics API has **no proxy**: a `Meter` fetched via `metrics.getMeter()` before `setGlobalMeterProvider()` runs is a permanent no-op forever after, even once a provider registers later. `getMeter()` in `otel.ts` is therefore a function, not a const, and `genai-spans.ts` calls it lazily on first metric emission (`instruments()`, cached after).
 
-**Dependencies** (`packages/server/package.json`): `@opentelemetry/api` 1.9.1, `api-logs` 0.222.0, `sdk-trace-node` / `sdk-trace-base` / `sdk-metrics` / `sdk-logs` / `resources` 2.11.0, `exporter-trace-otlp-proto` / `exporter-metrics-otlp-proto` / `exporter-logs-otlp-proto` 0.222.0, `semantic-conventions` 1.43.0. No gRPC exporter (see [Rejected alternatives](#rejected-alternatives)).
+**Dependencies** (`packages/server/package.json`): `@opentelemetry/api` 1.9.1, `api-logs` 0.222.0, `sdk-trace-node` / `sdk-trace-base` / `sdk-metrics` / `resources` 2.11.0, `sdk-logs` / `exporter-trace-otlp-proto` / `exporter-metrics-otlp-proto` / `exporter-logs-otlp-proto` 0.222.0, `semantic-conventions` 1.43.0. No gRPC exporter (see [Rejected alternatives](#rejected-alternatives)).
 
-**Test coverage**: `packages/server/test/observability-genai-spans.test.ts` (7 cases) drives `beginTurn` / `onAgentEvent` / `endTurn` against an in-memory tracer + `InMemorySpanExporter`, asserting the three-level span tree, parent ids, semconv attribute names, and the `capture_content` on/off split.
+**Test coverage**: `packages/server/test/observability-genai-spans.test.ts` (8 cases) drives `beginTurn` / `onAgentEvent` / `endTurn` against an in-memory tracer + `InMemorySpanExporter`, asserting the three-level span tree, parent ids, semconv attribute names, and the `capture_content` on/off split.
 
 ## Span model
 
@@ -87,7 +87,7 @@ Child of `invoke_agent`, one per model call — created retroactively on the `us
 | `gen_ai.input.messages` | | semconv JSON (see below) — **delta only**: messages appended since this turn's previous `chat` span (first call → the user message; later calls → that cycle's `tool_result`s) |
 | `gen_ai.output.messages` | | semconv JSON, only the trailing assistant message |
 
-Semconv message JSON: `[{role, parts:[{type:"text",content}|{type:"tool_call",id,name,arguments}|{type:"tool_call_response",id,result}]}]`.
+Semconv message JSON: `[{role, parts:[{type:"text",content}|{type:"tool_call",id,name,arguments}|{type:"tool_call_response",id,response}]}]`.
 
 `gen_ai.input.messages` is incremental on purpose (since 1.3.1): replaying the full history on every model call made a turn's exported bytes O(n²) and the system prompt alone was ~60% of the volume — a 4-turn / 9-call session dropped from 129 KB to 44 KB of content attributes. Nothing is lost: the full conversation for a trace is the concatenation of its `chat` spans' input + output deltas in order (a `TurnState.messageCursor` tracks the boundary; a mid-turn compact that shrinks the history yields an empty delta and re-syncs the cursor). Verified that AgentCore Evaluations scores are unchanged — its evaluators read `invoke_agent`'s `task.*` and `execute_tool`'s `arguments/result`, not the chat messages.
 
@@ -105,7 +105,7 @@ Child of the `chat` span that requested it, one per tool call — created on the
 | `gen_ai.tool.call.arguments` | | JSON |
 | `gen_ai.tool.call.result` | | text, empty → `[no output]` |
 
-Tool calls still pending when `endTurn` fires (turn interrupted/aborted mid-cycle) are closed as orphans with status `ERROR` and `halo.tool.orphaned=true`, so no trace is left with a dangling tool-call id.
+Tool calls still pending when `endTurn` fires (turn interrupted/aborted mid-cycle) are closed as orphans (no status set) with `halo.tool.orphaned=true`, so no trace is left with a dangling tool-call id.
 
 All content attributes are capped (32 KB general cap, 2 KB per message part, 8 KB for system instructions); over-cap content is truncated with a `…[truncated N chars]` marker, and an over-cap message list drops the oldest messages first with an omission marker.
 

package/bundled-docs/design/prompt-system.md

@@ -2,7 +2,7 @@
 
 On agent startup, Halo assembles the system prompt by concatenating various MD files in a fixed order.
 
-Entry point: `session-manager.ts` `buildAgentInstance(agentId, sessionId, parentId?, workingDir?, accessLevel?)`
+Entry point: `session-agent-builder.ts` `SessionAgentBuilder.buildAgentInstance(agentId, sessionId, parentId?, workingDir?, accessLevel?)`
 
 **Root agent rule**: `!parentId` (parentId null/undefined = root). Does not depend on any `is_default` field.
 
@@ -17,7 +17,7 @@ Entry point: `session-manager.ts` `buildAgentInstance(agentId, sessionId, parent
 ├── prompts/                ← user-editable system prompts (externalised)
 │   ├── bootstrap/BOOTSTRAP.md             ← first-run guidance
 │   ├── all/                               ← every-agent rules (TOOL_GUIDELINES.md, TOOL_SHELL[.windows].md, WORKSPACE_CONVENTIONS.md, RUNTIME.md)
-│   └── root/                              ← root-agent-only (empty by default; user-set)
+│   └── root/                              ← root-agent-only (DELEGATION.md, WORKSPACE_MEMORY.md)
 ├── agents/<id>/{agent.yaml, AGENT.md}
 └── skills/<id>/SKILL.md       ← built-in `halo` skill carries platform self-knowledge (loaded on demand via activate_skill)
 ```
@@ -52,7 +52,7 @@ Resolution is by the agent's **folder** (`agentSourceDir`), not per file:
 agent entirely (both `agent.yaml` and `AGENT.md`), with no per-file fallback
 to global — a missing file inside it is just absent. YAML fields: `name` /
 `description` / `model` / `tools` / `skills` / `system_prompt` / `context` /
-`priority`.
+`priority` / `internal` / `team`.
 
 ## Step 2 — Resolve MD file paths
 
@@ -127,14 +127,14 @@ Startup seeds `templates/prompts/{bootstrap,all,root}/` into `~/.halo/global/pro
 
 Replacement is **whole-file**, not per-section — so split the platform-divergent content into its own file and keep the common content in an un-suffixed file. Example in `prompts/all/`: `TOOL_GUIDELINES.md` (common) + `TOOL_SHELL.md` (unix Shell section) / `TOOL_SHELL.windows.md` (cmd.exe, `dir`/`findstr`, `%USERPROFILE%`, `python` vs `python3`, `.py` skill caveats). To add a new platform difference anywhere, extract that block to `FOO.md` and add `FOO.windows.md`.
 
-Result:
-- `prompts/bootstrap/*.md` → `bootstrapPrompt`
-- `prompts/all/*.md` → `allPrompt`
-- `prompts/root/*.md` → `rootPrompt`
+Result (the returned `systemPrompts` object; the sections below write these fields as `bootstrapPrompt` / `allPrompt` / `rootPrompt`):
+- `prompts/bootstrap/*.md` → `systemPrompts.bootstrap`
+- `prompts/all/*.md` → `systemPrompts.all`
+- `prompts/root/*.md` → `systemPrompts.root`
 
 Missing directory or read failure: warn + use built-in fallback.
 
-`loadSystemPrompts` also returns `files: { bootstrap: string[]; all: string[]; root: string[] }` — the absolute paths of the `.md` files actually read for each scope (empty when the built-in fallback was used). `session-manager.ts` forwards this list into `AgentMeta.mdFiles`, which `/session context` renders one line per file (label `prompt/<scope>/<basename>`). When a scope falls back to the built-in constants, a single line `prompt/<scope> (built-in fallback): <dir>` is shown instead.
+`loadSystemPrompts` also returns `files: { bootstrap: string[]; all: string[]; root: string[] }` — the absolute paths of the `.md` files actually read for each scope (empty when the built-in fallback was used). `session-agent-builder.ts` forwards this list into `AgentMeta.mdFiles`, which `/session context` renders one line per file (label `prompt/<scope>/<basename>`). When a scope falls back to the built-in constants, a single line `prompt/<scope> (built-in fallback): <dir>` is shown instead.
 
 ## Step 5 — Compose the MD prompt
 
@@ -159,8 +159,8 @@ Global and workspace-root INSTRUCTIONS share the same `## User Instructions` hea
 mdPrompt                                         ← incl. roster + working_dir scope (both inside composeMdPrompt)
 + "\n\nThe project workspace is at: {workspaceRoot}\n"
 + [optional] "Working directory: {workingDir}\n"
-+ allPrompt
 + rootPrompt
++ allPrompt
 ```
 
 (The `working_dir` directory-chain INSTRUCTIONS.md live *inside* `mdPrompt` — folded into the `## User Instructions` region by `composeMdPrompt` — not after the `Working directory:` tagline. That tagline is just a one-line focus marker.)
@@ -216,7 +216,7 @@ If `mdPrompt` is empty:
 
 ## Step 7 — Append skills and tool list
 
-[session-manager.ts:682-697](../../../packages/server/src/agents/session-manager.ts#L682)
+[session-agent-builder.ts](../../../packages/server/src/agents/session-agent-builder.ts) `composeSystemPrompt`
 
 ### Skills (progressive disclosure)
 
@@ -245,7 +245,7 @@ AGENT.md                                         ← workspace > global
 ## Your Team                                    ← roster (dropped when team is empty/unset)
 ## User Instructions                             ← ~/.halo/global/INSTRUCTIONS.md (suppressed when ws has its own)
 ## User Instructions                             ← <ws>/.halo/INSTRUCTIONS.md (workspace root)
-## Project Knowledge                             ← <ws>/.halo/INDEX.md (or nudge)
+## Project Knowledge                             ← <ws>/.halo/INDEX.md (skipped when absent)
 "The project workspace is at: ..."
 "Working directory: ..."                         ← if workingDir is set
 rootPrompt                                       ← prompts/root/*.md (ws > global): DELEGATION.md, WORKSPACE_MEMORY.md
@@ -403,4 +403,4 @@ Schema declared by each package + values stored centrally is the same model VSCo
 - **Bootstrap trigger**: `!parentId && !userMd`
 - **System prompts are external**: resolved from workspace then global `prompts/{bootstrap,all,root}/*.md`, read live, sorted by filename.
 - **System prompt missing**: warn + use built-in fallback; `system-prompts.ts` is the seed source and fallback
-- **`.halo/` is not grep/globbed**: use `file_read` + INDEX.md navigation
+- **`.halo/` is grep/globbed** except its runtime subtrees (`sessions/ logs/ evo/ tmp/ assets/ canvas/`)

package/bundled-docs/design/session.md

@@ -82,9 +82,9 @@ Manages every agent session's lifecycle (root + sub-agent). Each session is 1:1
 
 | Method | Purpose |
 |---|---|
-| `createSession(agentId, parentId, description, agentName?, explicitId?, workingDir?, accessLevel?)` | Create a session (SQLite + memory). `workingDir` = absolute path at runtime, stored as workspace-relative in DB; null = project root. `accessLevel` = `'readonly'`, `'workspace'`, or `null` (full). |
-| `sendUserMessage(sessionId, text, images?)` | Send a message — run immediately if idle, queue if busy |
-| `compactSession(sessionId)` | LLM-summary compact |
+| `createSession(agentId, parentId, description, agentName?, explicitId?, workingDir?, accessLevel?, title?)` | Create a session (SQLite + memory). `workingDir` = absolute path at runtime, stored as workspace-relative in DB; null = project root. `accessLevel` = `'readonly'`, `'workspace'`, or `null` (full). |
+| `sendUserMessage(sessionId, text, images?, accessLevel?)` | Send a message — run immediately if idle, queue if busy; returns `'running'` or `'queued'` |
+| `compactSession(sessionId, opts?)` | LLM-summary compact (`opts.onProgress` for UI progress) |
 | `interruptSession(sessionId)` | Abort the in-flight turn now (fire-and-forget); `interruptRequested` is set so the unwind repairs rather than errors, then the queued message drains. Shared by esc and the `interrupt_session` tool |
 | `stopSession(sessionId)` | Fold the whole `messageQueue` into `agent.messages` (preserve, don't drop), abort + repair, no re-run, sets `stoppedAt`. Cascades to descendants |
 | `deleteSession(sessionId)` | Cascade-delete a session and all descendants (SQLite) |
@@ -196,7 +196,7 @@ A `QueuedMessage` is `{ text, sourceSessionId?, images? }`: `sourceSessionId` is
 
 **Arrival stamp.** Both paths run the turn through `runAgentTurn`, which prepends `[<ISO-8601 UTC>] ` (e.g. `[2026-09-12T15:17:44.153Z] `) to the first text block of the model-facing input — an image-only input gets a stamp-only text block unshifted. The model has no clock; without this it couldn't tell a reply that came two days later from one that came instantly, or how long a sub-agent report took to land. Stamped **once, before the retry loop**, so every attempt (and the [multimodal 4xx degrade](#multimodal-4xx-degrade) rebuild) reuses the identical input. Agent reports therefore read `[<iso>] (from: session X)\n…` — stamp outermost, no special-casing. Only `agent.messages` changes: the UI `type:'user'` event keeps the raw text (see [Turn matching](#exchange-deletion-soft-ui--hard-raw) for the strip on compare), and the self-compact instruction / `[Conversation Summary]` injection / `tool_result` messages are never stamped.
 
-**Final-text flag.** The agent loop marks each text block `final` when the model call ended for a reason other than `tool_use` (i.e. it is the turn's wrap-up, not the filler emitted before a tool call), and `runAgentTurn`'s `case 'text'` forwards it on the `stream` event as `AgentSessionEvent.final`. Block-send consumers gate on it: the channel responders (wechat / telegram / slack / feishu) append only `final` text, and `halo cli` prints the last root turn's `final` text as its stdout (fallback: that turn's full text). `finalOutput` (used by `tryReportToParent`) is the same accumulation on the server side. Streaming providers additionally yield `text_delta` / `thinking_delta` events during the model call (forwarded as `stream_delta` / `thinking_delta`, UI-only); they never touch `output` / `finalOutput` — those only ever see the whole `text` event, which follows every completed call exactly as before. The one place the loop itself keeps the text deltas is the interrupted-stream landing (see [Partial streamed text lands](#conversation-repair)): a call cancelled mid-stream pushes what it had streamed as a marked assistant turn so the model's history matches what the UI showed.
+**Final-text flag.** The agent loop marks each text block `final` when the model call ended for a reason other than `tool_use` (i.e. it is the turn's wrap-up, not the filler emitted before a tool call), and `runAgentTurn`'s `case 'text'` forwards it on the `stream` event as `AgentSessionEvent.final`. Block-send consumers gate on it: the channel responders (wechat / telegram / slack / feishu / wecom) append only `final` text, and `halo cli` prints the last root turn's `final` text as its stdout (fallback: that turn's full text). `finalOutput` (used by `tryReportToParent`) is the same accumulation on the server side. Streaming providers additionally yield `text_delta` / `thinking_delta` events during the model call (forwarded as `stream_delta` / `thinking_delta`, UI-only); they never touch `output` / `finalOutput` — those only ever see the whole `text` event, which follows every completed call exactly as before. The one place the loop itself keeps the text deltas is the interrupted-stream landing (see [Partial streamed text lands](#conversation-repair)): a call cancelled mid-stream pushes what it had streamed as a marked assistant turn so the model's history matches what the UI showed.
 
 **drainQueue** folds the **whole queue** into ONE merged follow-up turn per round, re-checking after each round (a fresh interrupt or a sibling's report can land mid-drain):
 - The batch is `splice(0)`'d; agent entries keep a `(from: session X)` prefix, user entries fold raw, and all entries' `images` are merged in.
@@ -205,7 +205,7 @@ A `QueuedMessage` is `{ text, sourceSessionId?, images? }`: `sourceSessionId` is
 
 **`complete` invariants** (root only):
 - The **terminal** `complete` is emitted from `runSession`'s `finally`, and `promise = null` is set **before** emitting it — the CLI / web stream-close logic gates on `complete && !hasRunningSessions()`, which reads `promise !== null`; emitting `complete` first would leave the session still "running" at the moment the client decides whether to close.
-- **`batchBoundary` complete**: when a merged round finishes **and the queue still has a next round**, `drainQueue` emits `{ type: 'complete', batchBoundary: true }`. This is a per-round flush signal for **block-oriented channels** (wechat / telegram / slack / feishu), which buffer streamed text and only ship a message on `complete` — without it, N drain rounds buffer into one blob that lands only at the terminal `complete` ("8 reports in one lump"). **Stream-terminating consumers (web-channel SSE, ACP) must ignore `batchBoundary` and keep the stream open** — the root is still running and more output follows; only the terminal (unmarked) `complete` closes the stream. See [web.md](web.md) and the per-channel coalescing notes (e.g. [wechat.md](wechat.md)). The field is **not** carried into the WS protocol — admin closes its bubble on `chat:complete` either way.
+- **`batchBoundary` complete**: when a merged round finishes **and the queue still has a next round**, `drainQueue` emits `{ type: 'complete', batchBoundary: true }`. This is a per-round flush signal for **block-oriented channels** (wechat / telegram / slack / feishu / wecom), which buffer streamed text and only ship a message on `complete` — without it, N drain rounds buffer into one blob that lands only at the terminal `complete` ("8 reports in one lump"). **Stream-terminating consumers (web-channel SSE, ACP) must ignore `batchBoundary` and keep the stream open** — the root is still running and more output follows; only the terminal (unmarked) `complete` closes the stream. See [web.md](web.md) and the per-channel coalescing notes (e.g. [wechat.md](wechat.md)). The WS `chat:complete` frame carries the field too — admin closes its bubble either way but rings the finish bell only on the terminal one.
 
 **Three-tier interrupt model** — two **soft** paths and one **hard** path, distinguished by *when* the abort fires, never by whether the message is kept (all three preserve the queue):
 1. **`query_session` while busy — soft interrupt.** `querySession(..., interrupt=false)` enqueues **and** sets `interruptRequested` (same as a user message). This is what makes a sub-agent fold two queued questions into **one merged answer** instead of replying one-by-one: the in-flight turn unwinds after its current tool, then `drainQueue`'s `splice(0)` folds every message that landed alongside it into a single round — matching how root handles two user messages. An **idle** target has no turn to interrupt, so it just runs the message directly.
@@ -229,7 +229,7 @@ A hard interrupt aborts the turn's `AbortSignal`, which `agent-loop.ts` forwards
 
 - **`full` access (non-Windows)** spawns via `spawn(command, { shell: true, detached: true })` so the command becomes a **process-group leader** (`pgid === child.pid`). On abort *or* timeout, `process.kill(-pid, 'SIGTERM')` signals the **whole group**, so a compound command's worker dies with the shell.
 - **Why not `execAsync(command, { signal })`** (the previous implementation): `exec` wraps the command in `/bin/sh -c "<command>"` and, on abort, only SIGTERMs that `sh`. A compound command (`sleep 60 && …`) has already forked the real worker (`sleep`) as a child of `sh` — the signal never reaches it, so it **reparents to init (PPID 1) and runs to completion as an orphan**. The agent turn unwinds correctly (the promise rejects), but the command keeps running, which made `interrupt_session` *look* like it didn't really interrupt. Single non-compound commands didn't expose it (Node optimizes them to a direct `exec` with no `sh` layer).
-- **`workspace` / `readonly` access** run under `bwrap` with `--die-with-parent`, a kernel-level guarantee that the sandboxed child dies with its parent — that path was never affected and is unchanged. **Windows** `full` keeps the `execAsync` path (no process groups; the orphan case doesn't arise the same way).
+- **`workspace` / `readonly` access** run under `bwrap` with `--die-with-parent`, a kernel-level guarantee that the sandboxed child dies with its parent — that path was never affected and is unchanged. On macOS they run under Seatbelt (`sandbox-exec`) through the same `spawnGroupExec` group kill. **Windows** `full` keeps the `execAsync` path (no process groups; the orphan case doesn't arise the same way).
 
 The `spawnGroupExec` helper preserves `promisify(exec)`'s contract exactly: resolve `{ stdout, stderr }` on exit 0; reject with an `Error` carrying `.message` / `.stdout` / `.stderr` / `.code` otherwise (abort rejects with `name: 'AbortError'`). Covered by `test/sandbox-process-group.test.ts`, which asserts by side effect — a sentinel file the orphaned worker *would* create must never appear after the abort.
 
@@ -375,7 +375,7 @@ Frontend network issues don't affect the backend:
 | **4xx multimodal rejection** (`Multimodal data is corrupted` / `Could not process image`) | Replace all image blocks in history with text placeholders, persist, retry — see [Multimodal 4xx degrade](#multimodal-4xx-degrade) below |
 | Unrecoverable error | Report to user, stop |
 
-**Refusal stop.** `stop_reason: "refusal"` (Anthropic models on Bedrock invoke + generic anthropic) is an HTTP 200 with `stop_details {category, explanation}` — not an error, so it never enters the retry matrix above. `agent-loop.ts:208` handles it explicitly: no assistant message is pushed, any partial `tool_use` is **not** executed, the loop ends; `session-manager.ts:1226` emits a `system` event `⚠️ [<agent>] Model declined to respond (<category>): <explanation>` suggesting `/new`. Previously it fell through the `end_turn` path and looked like a silent stall.
+**Refusal stop.** `stop_reason: "refusal"` (Anthropic models on Bedrock invoke + generic anthropic) is an HTTP 200 with `stop_details {category, explanation}` — not an error, so it never enters the retry matrix above. `agent-loop.ts` handles it explicitly: no assistant message is pushed, any partial `tool_use` is **not** executed, the loop ends; `session-manager.ts` emits a `system` event `⚠️ [<agent>] Model declined to respond (<category>): <explanation>` suggesting `/new`. Previously it fell through the `end_turn` path and looked like a silent stall.
 
 **Classification order: structured signal first, message text last.** The interrupt branch is decided by the attempt's own `AbortController` signal (every interrupt path we own goes through `abortReason()` on it), never by the words `cancelled` / `aborted` in the message — an upstream error body can legitimately read `"The operation was aborted due to …"` (Bedrock), and matching that swallowed a real failure as a user interrupt: silent `break`, no retry, no error event, an empty reply. Likewise the account-level branch trusts `httpStatus` when one was recovered: 401/402/403 is terminal, any *other* status is not, whatever the body says — an OpenAI-compatible 503 whose body reads `"authentication service temporarily unavailable"` used to be classified as a dead key and never retried. The keyword list is only consulted when no status could be extracted. Pinned by `turn-retry-idempotent.test.ts` (five classification cases).
 
@@ -401,7 +401,7 @@ The transient-5xx branch is the one that all providers share, and getting the **
 
 **Retry decision** — a failure is treated as a transient server-side error (→ retry with backoff) when **either**:
 
-- `err.name` is `InternalServerException`, `ModelTimeoutException`, or `ServiceUnavailableException`; **or**
+- `err.name` is `InternalServerException`, `ModelTimeoutException`, `ModelStreamErrorException`, or `ServiceUnavailableException`; **or**
 - the extracted `httpStatus` is one of `500` / `502` / `503` / `504` / `529` (Anthropic "Overloaded") / `408` (request/model timeout).
 
 Throttling is checked the same way one branch earlier — structured `ThrottlingException` name or status 429 first, message keywords second; the real Bedrock throttle message ("Too many requests, please wait before trying again.") carries no keyword, so the name/status check is what catches it.
@@ -418,7 +418,7 @@ Three entry points with different quality / safety trade-offs:
 |---|---|---|---|
 | 90% soft threshold (mid-turn auto) | `maybeAutoCompact()` via agent-loop's `beforeCallModel` hook — runs before each model call within a turn | **Self-compact** (`selfCompactSession`) — the agent summarizes its own context, then a tail micro-compact pass clears bulk tool output. **Not interruptible, no wall-clock cap; local fallback** if the summary throws, idle-times-out or comes back empty (see below) | The agent already has full context cached (prompt cache hit). No extra model call, no input duplication, no risk of losing tool_result semantics. Firing mid-turn (not just at turn end) stops a single long turn that accumulates many large tool results from blowing the window. |
 | Overflow mid-loop (`too many input tokens`, `Input is too long`, …) | `runAgentTurn` retry catch → `localCompactMessages` → retry | **Local** — `[role]: <first N chars>` concat, no network call | The model just refused this payload; an LLM round-trip now could stall the recovery path. Local is deterministic and instant; the next end-of-turn can re-summarize via self-compact. |
-| User `/session compact` (web, WeChat) | `commands/compact.ts` / `SessionManager.compactSession` | **Self-compact**, cancellable, **no local fallback** | User explicitly requested it; self-compact reuses the cached context so it's fast. A failure (model error / idle timeout) leaves the context unchanged (`Compaction failed — context unchanged`) and is rethrown to the caller; an empty summary emits `Compaction skipped — no summary produced`. |
+| User `/session compact` (web, WeChat) | `channels/shared/commands.ts` (admin WS: `ws/handler.ts`) / `SessionManager.compactSession` | **Self-compact**, cancellable, **no local fallback** | User explicitly requested it; self-compact reuses the cached context so it's fast. A failure (model error / idle timeout) leaves the context unchanged (`Compaction failed — context unchanged`) and is rethrown to the caller; an empty summary emits `Compaction skipped — no summary produced`. |
 
 Self-compact **deep-snapshots the keep-region before running the summarize turn** (`messages.slice(cut).map(structuredClone)`), then injects a summarization instruction into the agent's own stream, captures the response, and rebuilds messages as `[summary + snapshot]`. This reuses the provider's prompt cache (no separate model needed) and preserves full semantic context including tool results.
 
@@ -426,7 +426,7 @@ The pre-run snapshot is load-bearing, not an optimization: `agent.run()` coalesc
 
 As a final byte-trimming step, self-compact runs **micro-compact** over that snapshot (`microCompactMessages(cleanRecent, 1)`). Each kept-recent message may still carry a large tool result (e.g. a 50 KB `file_read`), so after summarizing it would otherwise re-cross the threshold immediately. Micro keeps only the newest `tool_result`'s content and clears the rest in place, preserving `tool_use_id` pairing so the next API call stays valid — no extra LLM round-trip. Micro-compact is **not** a standalone compaction path; `selfCompactSession` is its only call site — self-compact is the entry point, micro is its tail cleanup.
 
-All paths share the same split logic — `compactCut(messages)`, exported from `agents/compact.ts` (single source of truth for SessionManager — `selfCompactSession` + the two feasibility gates below — and `localCompactMessages`): keep the last `keepMessages` turns, advance the cut forward past any orphan `tool_result`-first user message (otherwise the next API call gets `unexpected tool_use_id`). The tail loop only ever moves the cut *up*, so `cut === 0` is exactly the `messages.length <= keepMessages` "nothing to compact" case.
+All paths share the same split logic — `compactCut(messages)`, exported from `agents/compact.ts` (single source of truth for SessionManager — `selfCompactSession` + the two feasibility gates below — and `localCompactMessages`): keep the last `keep_messages` turns, advance the cut forward past any orphan `tool_result`-first user message (otherwise the next API call gets `unexpected tool_use_id`). The tail loop only ever moves the cut *up*, so `cut === 0` is exactly the `messages.length <= keep_messages` "nothing to compact" case.
 
 **Bounds and Stop.** Self-compact has no wall-clock timeout: a long but still-streaming summary is fine, and a hung call is bounded only by the model-call idle timeout (`timeout.model_request`, re-armed on any data the stream delivers; expiry throws `MODEL_TIMEOUT_ERROR`). An **auto-compact is not interruptible** — `maybeAutoCompact` passes no signal. Stop / Esc (`stopSession`, `interruptSession`, `stopUserSession`, WS `chat:stop` / `chat:interrupt`, `/api/web/stop`) abort only the turn's own controller, which the loop checks once `beforeCallModel` returns, so they take effect after the compact finishes (the stop request itself waits until then). Messages arriving meanwhile queue and run as the next turn once the compact ends; a Stop that folds the queue into history during the compact parks the text in `foldAfterCompact`, and `clearCompacting` lands it on the post-compact history (`foldIntoAgentMessages`). A **manual `/compact`** has no turn, so `cancelCompact` (WS `chat:stop` / `chat:interrupt`, channel `/stop` / `/interrupt` and `POST /api/web/stop` while compacting with no turn running, and `stopUserSession`) cancels it: history rolls back and `Compact cancelled` is emitted.
 
@@ -438,7 +438,7 @@ All paths share the same split logic — `compactCut(messages)`, exported from `
 
 **Local compact output is API-legal on its own.** `localCompactMessages` returns `[summary, ...recent]` where `recent` starts past any `tool_result`-first user message, so every kept `tool_result` has its `tool_use` in the kept tail and `repairConversationMessages` is a no-op on the result (also on a second pass over its own output). Pinned by `local-compact-roundtrip.test.ts` — without it the overflow retry would only have "worked" via the later corrupted-conversation repair retry.
 
-Config (see `config.compact`): `keepMessages` / `maxSummaryInput` / `maxMessageSlice` — editable in Settings → General → compact.
+Config (see `config.compact`): `keep_messages` / `max_summary_input` / `max_message_slice` (settings keys `general.compact.*`) — editable in Settings → General → compact.
 
 **Self-compact also archives the UI log.** `selfCompactSession` calls `uiStore.archiveOldMessages(session.id)` for **root and sub-sessions alike** (root-only until 1.5.3-alpha; a long-running sub-agent's UI log then grew without bound — 4.77 MB in testing), right before the compaction notice is emitted so the notice lands in the kept exchange rather than inside the archived segment. Compaction is the one path that already means "history shrinks here", which is why archiving hangs off it rather than off a timer or its own sweep — the size threshold below decides whether the call does anything. See [UI-log archiving](#ui-log-archiving).
 
@@ -464,7 +464,7 @@ Files: `packages/server/src/sessions/session-archive.ts` (segment IO) · `agents
 
 **Trigger: file size.** A compact archives only when the active `<seg>.json` is larger than `ARCHIVE_SIZE_THRESHOLD = 3 MB` (one `statSync`; a missing file counts as 0, so the check is also the "nothing written yet" guard). Below it, `archiveOldMessages` returns 0 and touches nothing, however many exchanges have piled up.
 
-Bytes, not an exchange count, because bytes are the actual problem — file size is what makes a log slow to read, parse and ship — and per-exchange size varies by ~three orders of magnitude (a bare "yes" versus a turn carrying several 50 KB tool results), so a count is a badly distorted proxy: the same "15 exchanges" is 40 KB in one session and 40 MB in another. It is also self-limiting: after an archive the file restarts near-empty, so it must grow another 3 MB of real content before the next segment, which bounds segment count by total bytes written rather than by how often the user compacts. Still no relation to `config.compact.keepMessages` (that counts raw LLM messages — a different granularity with no honest mapping to UI rows), and no setting: one constant, tuned once.
+Bytes, not an exchange count, because bytes are the actual problem — file size is what makes a log slow to read, parse and ship — and per-exchange size varies by ~three orders of magnitude (a bare "yes" versus a turn carrying several 50 KB tool results), so a count is a badly distorted proxy: the same "15 exchanges" is 40 KB in one session and 40 MB in another. It is also self-limiting: after an archive the file restarts near-empty, so it must grow another 3 MB of real content before the next segment, which bounds segment count by total bytes written rather than by how often the user compacts. Still no relation to `config.compact.keep_messages` (that counts raw LLM messages — a different granularity with no honest mapping to UI rows), and no setting: one constant, tuned once.
 
 **Split point.** Over the threshold, `archiveSplitIndex(messages, 1)` keeps only the **newest main user exchange** (`role === 'user'` without `taskId` — the same subset the admin renders and `deleteExchange` counts ordinals over) and cuts at its start, so a turn's responses are never split from their user message. A log holding a single exchange yields cut 0 and is left alone: there is nothing to move without splitting the turn the user is looking at, so an oversized *single* exchange is deliberately not archived.
 

package/bundled-docs/design/slack.md

@@ -61,7 +61,7 @@ Files: `packages/server/src/channels/slack/`
 - `types.ts` — SlackAccount, SlackSocketEnvelope, SlackMessageEvent interfaces
 - `accounts.ts` — DAL (thin wrapper over `channels/shared/accounts.ts` for Slack-specific mappings)
 - `handler.ts` — Socket Mode connection + event routing, mention filtering; session resolution + per-thread listener/route bookkeeping come from `channels/shared/inbound.ts` (`InboundBridge` / `deliverInbound` / `dispatchChannelCommand`)
-- `event-adapter.ts` — AgentSessionEvent → Slack messages (buffer + flush; split at 35k chars)
+- `event-adapter.ts` — AgentSessionEvent → Slack messages (buffer + flush on `complete`; split at 35k chars)
 - `api.ts` — HTTP client (auth.test / openSocketModeConnection / chat.postMessage / files.upload / files.download / searchSlackTargets)
 - `cron-dispatcher.ts` — CronDispatcher registration; requires an explicit Slack chatId per dispatch
 
@@ -109,13 +109,13 @@ Unlike Telegram (grammy polling) or WeChat (HTTP long-poll), Socket Mode elimina
 
 1. SessionManager emits AgentSessionEvent stream chunks
 2. SlackResponder buffers only chunks flagged `final` (the turn's wrap-up text; pre-tool-call filler is dropped) until `complete` event
-3. On `complete` or when buffer hits 35k chars:
-   - Split at paragraph boundary if needed via the shared `splitText` (`channels/shared/chunk.ts`; Slack hard-caps messages at ~40k)
+3. On `complete` (Slack doesn't set `splitMidStream`, so the buffer is never flushed early at the limit):
+   - Split at the 35k-char limit, at a paragraph boundary if possible, via the shared `splitText` (`channels/shared/chunk.ts`; Slack hard-caps messages at ~40k)
    - Extract `MEDIA: <path>` markers (sent as native file uploads)
    - Convert CommonMark → Slack's mrkdwn format
    - Post as a single message (or series of messages if split)
    - This fires on **any** `complete`; the responder ignores its `batchBoundary` flag, so a multi-round queue drain posts each merged turn as its own message rather than one blob (see [session.md](session.md#message-queue-and-drain))
-4. Errors and system notices flush immediately (don't wait for complete)
+4. Errors (`❌ …`) and system notices (`ℹ️ …`) flush immediately (don't wait for complete)
 5. Sub-agent events (taskId set) are dropped (visible in web UI only)
 
 **Chunk sends are serialized per responder.** One `flushBuffer` can produce
@@ -125,7 +125,9 @@ previous one, so Slack could accept them out of order and a long reply arrived
 scrambled (audit A-L3). Each responder now keeps a `sendTail` promise chain and
 appends every chunk to it, so chunk *n+1* only goes out after *n* settles; a
 rejected link is absorbed (`dispatchChunk` logs its own send failures) so one
-bad send can't stall the rest of the reply.
+bad send can't stall the rest of the reply. The buffer + chain live in the
+shared `ChunkedResponder` (`channels/shared/responder.ts`), which slack / feishu
+/ wecom / wechat / telegram extend with their own limit and formatter.
 
 `close()` therefore returns that drain promise, and `InboundBridge` keeps the
 session's reply route registered until it settles before deleting it — including
@@ -138,20 +140,20 @@ dropped.
 
 ### DM sessions
 
-DM channels have a stable channel_id (`D…`). A message in a DM stays in the same session regardless of turn count. Session key: `slack:${channelId}:dm`.
+DM channels have a stable channel_id (`D…`). A message in a DM stays in the same session regardless of turn count. Session prefix: `slack_${channelId}:dm_`.
 
 ### Channel / group / thread sessions
 
-A mention on a top-level message starts a thread and creates a session keyed by that message's `ts`. Replies inside that thread reuse the same `thread_ts`, so they map to the same session and preserve context. Session key: `slack:${channelId}:${rootTs}`.
+A mention on a top-level message starts a thread and creates a session keyed by that message's `ts`. Replies inside that thread reuse the same `thread_ts`, so they map to the same session and preserve context. Session prefix: `slack_${channelId}:${rootTs}_`.
 
 ### Session resolution
 
-The `getOrCreateSessionForThread()` helper:
-1. Build session prefix: `slack:${channelId}:${rootTs}:`
-2. Check per-user activeOverrides (set by `/session switch` command in DMs)
-3. Look for an existing session matching the prefix + userId
-4. If none found, create a new session with ID `${prefix}${Date.now().toString(36)}`
-5. Store in activeOverrides for future messages from this user
+`handleInbound()` hands the message to `deliverInbound` (`channels/shared/inbound.ts`), which calls `getOrCreateChannelSession`:
+1. Build the session prefix with `buildSessionPrefixForThread(channelId, rootTs)` (see above; `rootTs` is `dm` for DMs); the override key is `${userId}@${channelId}:${rootTs}`
+2. `findActiveSessionId` (`channels/shared/commands.ts`): honour the per-user activeOverrides entry (set by `!session switch` in DMs), else the latest session under the prefix
+3. If none found, create one with ID `${prefix}${Date.now().toString(36)}` on the workspace's default agent and store it in activeOverrides (`setOverrideOnCreate`)
+
+**Reply route after a restart.** Routes and listeners are in-memory, so `startAccount` calls `restoreReplyRoute()`: it reads `lastActiveChatId` (`<channelId>:<rootTs>`) and re-wires the latest existing session under that prefix via `restoreChannelRoute` (no session is created), so a turn that resumes on its own after a restart still reaches Slack. Only that one conversation per account is restored; other threads re-wire on their next inbound message.
 
 ## Cron-dispatcher role
 
@@ -203,7 +205,7 @@ Text, images (base64 attached to agent input for vision), files. All files are d
 
 The agent runtime produces `MEDIA: <path>` markers. SlackResponder:
 - Intercepts the markers and calls `uploadFile()` for each one
-- Blocks sandbox violation for non-`full` accounts (files must be under workspace or /tmp — `isMediaPathAllowed(path, workspace, accessLevel)`; `full` accounts may send any readable path). A block throws inside the same try as the upload, so it surfaces as the `handler.upload_failed` text below
+- Blocks sandbox violation for non-`full` accounts (files must be under workspace or /tmp — `isMediaPathAllowed(path, workspace, accessLevel)`; `full` accounts may send any readable path). A block throws inside the same try as the upload (`sendMediaOrReport` in `channels/shared/media.ts`), so it surfaces as the `handler.upload_failed` text below
 - Falls back to error text if upload fails
 
 Outbound media uses Slack's v2 upload flow (getUploadURLExternal → signed PUT → completeUploadExternal).
@@ -218,9 +220,9 @@ Not supported: interactive messages (blocks/buttons/callbacks), slash commands i
 
 Slack-specific paths:
 
-- `packages/server/src/channels/slack/handler.ts:252` — `connect()` Socket Mode setup
-- `packages/server/src/channels/slack/handler.ts:391` — `handleInbound()` event dispatch
-- `packages/server/src/channels/slack/handler.ts:552` — `getOrCreateSessionForThread()` session keying
-- `packages/server/src/channels/slack/api.ts:265` — `openSocketModeConnection()` fetch wss:// URL
-- `packages/server/src/channels/slack/cron-dispatcher.ts:46` — `dispatch()` cron push logic
-- `packages/server/src/channels/slack/event-adapter.ts:90` — `dispatchChunk()` buffer flush + media extraction
+- `packages/server/src/channels/slack/handler.ts` `connect()` (inside `startSlackChannel()`) — Socket Mode setup
+- `packages/server/src/channels/slack/handler.ts` `handleInbound()` — event dispatch
+- `packages/server/src/channels/slack/handler.ts` `buildSessionPrefixForThread()` + `packages/server/src/channels/shared/inbound.ts` `deliverInbound()` / `getOrCreateChannelSession()` — session keying + resolution
+- `packages/server/src/channels/slack/api.ts` `openSocketModeConnection()` — fetch wss:// URL
+- `packages/server/src/channels/slack/cron-dispatcher.ts` `dispatch()` — cron push logic
+- `packages/server/src/channels/shared/responder.ts` — `ChunkedResponder.dispatchChunk()` buffer flush + media extraction (`slack/event-adapter.ts` supplies the 35k limit + `formatForSlack`)

package/bundled-docs/design/storage.md

@@ -11,8 +11,8 @@ Defines the persisted-data format for every Halo surface. Format changes must re
 │   ├── USER.md                        # User profile (bootstrap-generated)
 │   ├── prompts/                       # User-editable system prompts (externalised)
 │   │   ├── bootstrap/BOOTSTRAP.md     # First-run guidance
-│   │   ├── all/                       # Every agent (TOOL_GUIDELINES.md, TOOL_SHELL[.windows].md)
-│   │   └── root/                      # Root agent only — empty by default; user-set
+│   │   ├── all/                       # Every agent (TOOL_GUIDELINES.md, TOOL_SHELL[.windows].md, WORKSPACE_CONVENTIONS.md, RUNTIME.md)
+│   │   └── root/                      # Root agent only (DELEGATION.md, WORKSPACE_MEMORY.md)
 │   ├── agents/<id>/
 │   │   ├── agent.yaml                 # Agent config
 │   │   └── AGENT.md                   # Agent personality
@@ -26,7 +26,8 @@ Defines the persisted-data format for every Halo surface. Format changes must re
 │   ├── evo.db                         # Cross-workspace evolution queue (evolution_runs + evolution_applies)
 │   ├── cron.db                        # Cross-workspace cron jobs + run history (cron_jobs + cron_runs)
 │   ├── runs.db                        # Run ledger: (workspace, session_id) rows for server-driven runs in flight; steady state empty (running_sessions)
-│   ├── logs/                          # Runtime logs
+│   ├── extensions/<id>/               # Installed Canvas preview extensions (halo-extension.json + bundle)
+│   ├── logs/                          # Runtime logs (server.log)
 │   │   ├── evo/                       # Per-evo-run wrapper logs
 │   │   └── cron/                      # Per-cron-run cli stdout/stderr (30-day retention)
 │   ├── server.lock                    # Single-instance pid lock
@@ -62,7 +63,7 @@ Defines the persisted-data format for every Halo surface. Format changes must re
 ├── tmp/                                 # Agent scratch files (logs, downloads, intermediate artifacts) — convention from TOOL_GUIDELINES
 ├── assets/<channel>/inbound/<accountId>/<date>/  # Inbound media per channel (image/voice/video/file)
 ├── runtime.lock                       # Workspace runtime ownership marker (pid) — see below
-├── halo.db                           # Per-workspace sqlite (sessions metadata, command registry, disabled-items)
+├── halo.db                           # Per-workspace sqlite (sessions metadata, disabled-items)
 └── docs/                               # Project docs (requirements/design/dev/test/plans)
 ```
 
@@ -148,11 +149,11 @@ type MessageType =
 interface SessionMessage {
   // Required
   id: string                     // "m_{timestamp36}_{counter36}"
-  type: MessageType
+  type?: MessageType             // optional for backward compat (inferMessageType)
   role: 'user' | 'assistant' | 'system'
   content: string
   timestamp: number              // Unix ms
-  agentName: string
+  agentName?: string
 
   // Optional scope
   taskId?: string                // Sub-agent task ID
@@ -181,6 +182,9 @@ interface SessionMessage {
 
   // Transient (not persisted)
   streaming?: boolean
+
+  // Soft delete (deleteExchange) — greyed out in the UI, removed from raw context
+  deleted?: boolean
 }
 ```
 
@@ -287,12 +291,15 @@ interface AgentYamlConfig {
     maxTokens?: number
     promptCaching?: boolean | string
     thinking?: { enabled?: boolean; budget?: string; effort?: string }
+    verbosity?: string
   }
   system_prompt?: string
   tools?: string[]
   skills?: string[]
   context?: { maxTokens?: number; compressAt?: number }
   priority?: number
+  internal?: boolean    // platform tooling — off the roster, no workspace context
+  team?: string[]      // delegation whitelist; non-empty = can delegate
 }
 ```
 
@@ -335,7 +342,7 @@ general:                                  # built-in declarer (the server itself
     max_summary_input: 15000
     max_message_slice: 800
   sandbox:
-    hidden_dirs: "~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker,~/.config/gh"
+    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"
   logging:
     level: warn
@@ -388,7 +395,6 @@ A value of the form `<<ENV_NAME>>` is replaced at read time with `process.env.EN
 | `general.limits.grep_default_matches` | 50 | Default `grep` match cap when no explicit `max` is passed |
 | `general.limits.tool_result_render_chars` | 8000 | Per-tool-result cap on the content **fed to the LLM** (truncated with a re-run marker to protect the context window / prompt cache). The UI gets a much larger slice — see `tool_result_ui_chars` and `agent-loop.ts` (`resultContent` = LLM cap, `resultTextFull` = UI cap) |
 | `general.limits.tool_result_ui_chars` | 65536 | Per-tool-result cap on the content **stored for UI display** (admin/web chat panel). Far larger than the LLM cap so a normal command's full output stays visible, but bounded so a multi-MB `cat` can't bloat the session file / WS payload / browser render; excess truncated with a marker pointing at `file_read` |
-| `general.limits.ws_event_buffer` | 5000 | Events buffered per detached WS session before oldest are dropped on reattach |
 | `general.limits.terminal_scrollback_bytes` | 50000 | Off-screen scrollback bytes retained per detached persistent terminal |
 | `general.sandbox.hidden_dirs` | `~/.halo/secrets,~/.aws,~/.ssh,~/.gnupg,~/.docker,~/.config/gh,~/.halo/global/internal-sessions,~/.halo/global/logs` | Hidden from workspace/readonly sessions — bwrap tmpfs overlay (Linux) / Seatbelt deny (macOS) |
 | `general.sandbox.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` | Hidden from workspace/readonly sessions — bwrap bind of the empty `~/.halo/.sandbox-empty`, reads as empty (Linux) / Seatbelt deny (macOS) |
@@ -536,6 +542,8 @@ interface SkillMeta {
   name: string         // from frontmatter
   description: string  // from frontmatter
   path: string         // absolute path to SKILL.md
+  command?: string     // from frontmatter
+  requiresAccess?: 'full' | 'workspace' | 'readonly'  // from frontmatter
 }
 ```
 
@@ -552,16 +560,6 @@ The databases hold session metadata indexes and workspace-scoped preferences (e.
 
 ### Tables
 
-**`sessions`** — frontend session index (created on first chat)
-
-| Column | Type | Notes |
-|---|---|---|
-| id | TEXT PK | Session ID |
-| title | TEXT NOT NULL DEFAULT '' | Truncated first user message |
-| messages | TEXT | Legacy field, unused (content now in JSON) |
-| message_count | INTEGER | Message count |
-| created_at / updated_at | INTEGER | Unix ms |
-
 **`agent_sessions`** — agent session index (root + sub-sessions)
 
 | Column | Type | Notes |
@@ -602,7 +600,7 @@ All channel types (telegram, web, wechat, slack, feishu, wecom) share one table.
 | Column | Type | Notes |
 |---|---|---|
 | account_id | TEXT PK | Channel-specific ID (e.g. `halo_agent_bot`, `abc-im-bot`, `e718bb7b`) |
-| channel_type | TEXT NOT NULL | `'telegram'`, `'web'`, `'wechat'`, `'slack'`, or `'feishu'` |
+| channel_type | TEXT NOT NULL | `'telegram'`, `'web'`, `'wechat'`, `'slack'`, `'feishu'`, or `'wecom'` |
 | workspace_path | TEXT NOT NULL | Absolute path of the bound workspace |
 | label | TEXT | User-chosen name |
 | enabled | INTEGER | 1 = active, 0 = disabled |
@@ -620,6 +618,7 @@ All channel types (telegram, web, wechat, slack, feishu, wecom) share one table.
 | wechat | `botToken`, `baseUrl`, `userId`, `syncBuf` |
 | slack | `botToken`, `appToken`, `botUserId`, `teamId` |
 | feishu | `appId`, `appSecret`, `verificationToken`, `encryptKey`, `botOpenId` |
+| wecom | `botId`, `secret` |
 
 ### Schema change rules
 

package/bundled-docs/design/telegram.md

@@ -17,11 +17,11 @@ All channels are peers — each one is a subscriber + caller against SessionMana
 
 ## Shared inbound skeleton
 
-All four IM channels (telegram / wechat / slack / feishu) route inbound messages through `channels/shared/inbound.ts` rather than each keeping its own copy of the same ~200-line tail. The copies had drifted independently, which is how two audited bugs happened (audit A, 2026-08-06): the wechat responder captured its recipient at listener-registration time (A-M2), and all four command-dispatch sites ignored `CommandResult.startedTurn`, so a skill command on a fresh session kicked the agent with no listener attached and the reply vanished (A-M5).
+All five IM channels (telegram / wechat / slack / feishu / wecom) route inbound messages through `channels/shared/inbound.ts` rather than each keeping its own copy of the same ~200-line tail. The copies had drifted independently, which is how two audited bugs happened (audit A, 2026-08-06): the wechat responder captured its recipient at listener-registration time (A-M2), and all the command-dispatch sites ignored `CommandResult.startedTurn`, so a skill command on a fresh session kicked the agent with no listener attached and the reply vanished (A-M5).
 
 Three pieces:
 
-- **`InboundBridge<Route>`** — per-account bookkeeping for session listeners + their reply routes (`setRoute` / `getRoute` / `ensureListener` / `dropListener` / `closeAll`). The **reply route** — where to send, plus any per-message credential like wechat's context token — is a per-session value refreshed on **every** inbound message, and responders read it lazily at send time via `bridge.getRoute(sessionId)`. A listener registered once therefore can't lock onto a stale destination. Route entries are dropped together with their listener, so the map can't outgrow the listener set (the old per-channel context-token map never got cleaned up) — but **only once the responder has drained**: `close()` may return a promise (slack / feishu / wechat serialize their per-chunk sends and hand one back; telegram still fires each chunk and returns `void`), and the bridge defers the route deletion until it settles. Dropping the route synchronously stranded the tail of a split reply with nowhere to send (audit A-L3). `ensureListener` is idempotent per session; the account runner owns the bridge so `stopAccount` tears everything down with `closeAll()`, which walks the same per-listener teardown — deliberately no blanket `routes.clear()`, since that would delete the routes in-flight sends are about to read.
+- **`InboundBridge<Route>`** — per-account bookkeeping for session listeners + their reply routes (`setRoute` / `getRoute` / `ensureListener` / `dropListener` / `closeAll`). The **reply route** — where to send, plus any per-message credential like wechat's context token — is a per-session value refreshed on **every** inbound message, and responders read it lazily at send time via `bridge.getRoute(sessionId)`. A listener registered once therefore can't lock onto a stale destination. Route entries are dropped together with their listener, so the map can't outgrow the listener set (the old per-channel context-token map never got cleaned up) — but **only once the responder has drained**: `close()` returns a promise (every responder extends the shared `ChunkedResponder`, which serializes its per-chunk sends and hands the chain's tail back), and the bridge defers the route deletion until it settles. Dropping the route synchronously stranded the tail of a split reply with nowhere to send (audit A-L3). `ensureListener` is idempotent per session; the account runner owns the bridge so `stopAccount` tears everything down with `closeAll()`, which walks the same per-listener teardown — deliberately no blanket `routes.clear()`, since that would delete the routes in-flight sends are about to read.
 - **`deliverInbound`** — the tail itself: `rememberLastActiveChat` → access-level projection → resolve-or-create the channel session → busy/compacting hint (hint only; delivery continues regardless) → `setRoute` → `ensureListener` → `appendUserMessage(uiText)` + `sendUserMessage("[channel: X | user: Y | thread: Z]\n" + agentText)`. Returns the session id.
 - **`dispatchChannelCommand`** — wraps the shared `dispatchCommand` and, when the result says `startedTurn`, wires route + listener exactly like the plain-message path, so no channel can forget it again. A call site that can't build a route logs instead of attaching a responder that could never send.
 
@@ -37,6 +37,7 @@ One bot (= one BotFather token) is bound to one workspace. A workspace can bind
 
 - **One Telegram user → many sessions (one active at a time)**
 - Session ID format: `tg_<userId>_<createdAtBase36>` (e.g. `tg_123456789_m1abc`)
+- Keyed by the **sender** (`from.id`), not the chat: a user's DM and every group they talk to the bot in share the same sessions (see [Group chats](#group-chats))
 - Sessions live under the bot's bound workspace and use the highest-priority agent (falls back to `default` only when none exists)
 - The web side sees these sessions in the session list (labelled `Telegram: <userId>`)
 - Access level inherited from the bot account
@@ -61,7 +62,7 @@ Telegram-specific config JSON fields: `botToken`, `botUsername`, `allowedUsers`,
 
 Halo can send to a Telegram chat without that user having messaged the bot first — Telegram's Bot API allows `sendMessage(chatId, text)` for any known chat id. Halo only requires that the chat id come from a *trusted source*.
 
-The telegram cron-dispatcher (`channels/telegram/cron-dispatcher.ts`) registers itself with `cron/dispatcher.ts`'s registry at boot and **requires an explicit `chatId`** (numeric — Telegram private-chat ids equal user ids):
+The telegram cron-dispatcher (`channels/telegram/cron-dispatcher.ts`) registers itself with `cron/dispatcher.ts`'s registry at boot and **requires an explicit `chatId`** (numeric — Telegram private-chat ids equal user ids, group ids are negative):
 
 - Cron jobs created from inside a telegram chat via the `cron` skill auto-pin the current chat id (target `telegram:<account>:<chatId>`).
 - Admin-UI cron jobs that don't specify a target run silently — the result shows in the cron log, nothing is pushed.
@@ -69,6 +70,8 @@ The telegram cron-dispatcher (`channels/telegram/cron-dispatcher.ts`) registers
 
 Earlier drafts considered "fan-out to every id in `allowedUsers`" or "fall back to `lastActiveChatId`", but in practice both pushed the cron output to strangers' chats. The cron creator's intent is "reach me, the person who set this up" — so the only target is what the caller passes explicitly.
 
+The report is chunked like a chat reply — `splitText(text, TELEGRAM_TEXT_LIMIT)` (4000 chars, exported from `event-adapter.ts`; the Bot API rejects a message over 4096) — and the chunks are sent sequentially so a long report arrives in order. Before this the whole report went out in one `sendMessage` and anything over the cap failed outright. A failed chunk stops the send and is recorded as `chunk i/n: <error>` in the target's result row (chunks before it were delivered and stay); full success is one `ok` row regardless of chunk count. Same contract as the wechat dispatcher (see [cron.md](cron.md#dispatch-model)).
+
 ## Modules
 
 Files: `packages/server/src/channels/telegram/`
@@ -102,6 +105,20 @@ Routes: `packages/server/src/routes/telegram.ts`
 
 Photos / documents / voice / video notes trigger the same flow with the saved-file note in the text.
 
+Builtin commands (`bot.command`) run the same `allowedUsers` check first and reply `handler.not_allowed` on a miss — before, only plain messages were gated, so any member of a group the bot sat in could run `/session` / `/workspace switch` at the account's access level. A command with no sender (`channel_post` in a channel the bot administers) is ignored.
+
+### Group chats
+
+Supported, with Telegram's own visibility rules deciding what arrives:
+
+- **What the bot receives** — Telegram, not halo, filters. Bots default to *privacy mode* in groups: only `/cmd@thisbot`, replies to the bot's messages, and a few edge cases are delivered; disable privacy mode in BotFather (`/setprivacy`) or make the bot a group admin to receive every message. Halo has no @-mention gate of its own.
+- **Session isolation: per user.** The session prefix is `tg_<from.id>_` and the `activeOverrides` key is the user id, so each member gets their own session, and it is the *same* session they use in DM.
+- **Reply destination: the chat the message came from.** The route is `{ chatId: ctx.chat.id }`, so a group message is answered in the group. The route is refreshed per message — a reply follows the user's latest chat (DM or group).
+- **Permission check: the sender id.** `allowedUsers` matches `from.id` / `from.username`, never the chat id, for messages and commands alike.
+- **Commands** — `bot.command` matches `/cmd@thisbot` for builtins; the skill-command path strips an `@<this bot>` suffix the same way (a suffix naming another bot is left alone and falls through to chat).
+- **Restart restore** — `lastActiveChatId` stores the chat id; a group id is negative and doesn't name the member whose session it was, so `restoreReplyRoute` only restores private chats (`^\d+$`).
+- **Cron** — the dispatcher accepts any numeric chat id, negative group ids included; a cron created from inside a group auto-pins the group.
+
 ## Slash commands (native Telegram /commands)
 
 | Command | Purpose |
@@ -117,10 +134,11 @@ Photos / documents / voice / video notes trigger the same flow with the saved-fi
 
 ## Event coalescing (TelegramResponder)
 
-Same strategy as WeChat:
+Same strategy as WeChat — `TelegramResponder` is the shared `ChunkedResponder` (`channels/shared/responder.ts`) with `{ limit: 4000, logTag: 'Telegram', splitMidStream: true }`:
 - Buffer only `stream` events flagged `final` (the turn's wrap-up text; the filler the model emits before a tool call is dropped) until `complete`, then flush as one message
 - Flush happens on **any** `complete` — the responder doesn't read its `batchBoundary` flag, so a multi-round queue drain ships each merged turn as its own message instead of one blob (see [session.md](session.md#message-queue-and-drain))
-- If buffer exceeds 4000 chars (Telegram limit), split at paragraph boundary via the shared `splitText` (`channels/shared/chunk.ts`, used by all four responders)
+- If buffer exceeds 4000 chars (Telegram limit), split at paragraph boundary via the shared `splitText` (`channels/shared/chunk.ts`), mid-stream and again on flush
+- Every chunk goes through one serialized send chain, so a long reply arrives in order; `close()` returns the drain promise. Before this the telegram responder fired each chunk with `void dispatchChunk`, so the `sendMessage` calls raced and a >4000-char reply could land shuffled (the A-L3 fix had covered slack / feishu / wecom / wechat only)
 - `MEDIA:<path>` markers are intercepted and sent as native Telegram media
 - Errors flush immediately
 - Sub-agent events are dropped (visible in web UI only)
@@ -138,7 +156,7 @@ Outbound: the `send-file` skill produces `MEDIA:<path>` markers. The responder s
 - `.ogg/.oga` → `sendVoice`
 - anything else → `sendDocument`
 
-Path whitelist: a `full` account may send any readable path; other access levels are limited to the workspace or the OS temp dir (`isMediaPathAllowed(path, workspace, accessLevel)`). A blocked path — or any failed send — is reported to the chat as `t('handler.upload_failed')` (`⚠️ 文件上传失败：name — error`), same as slack / feishu / wecom; before this it was only a server log line.
+Path whitelist: a `full` account may send any readable path; other access levels are limited to the workspace or the OS temp dir (`isMediaPathAllowed(path, workspace, accessLevel)`). A blocked path — or any failed send — is reported to the chat as `t('handler.upload_failed')` (`sendMediaOrReport` in `channels/shared/media.ts`) (`⚠️ 文件上传失败：name — error`), same as slack / feishu / wecom; before this it was only a server log line.
 
 ## Configuration
 
@@ -170,6 +188,6 @@ curl -X POST http://localhost:9527/api/telegram/accounts \
 
 ## Scope and out-of-scope
 
-Supported: private chat text, photos, documents; slash commands; per-session access level; user whitelist; media sending.
+Supported: private and group chat text, photos, documents; slash commands; per-session access level; user whitelist; media sending.
 
-Not supported: group chats, inline queries, callback buttons, webhook mode (polling only).
+Not supported: inline queries, callback buttons, webhook mode (polling only).

package/bundled-docs/design/web.md

@@ -91,7 +91,9 @@ data: {"type":"complete"}
 data: {"type":"error","error":"..."}
 ```
 
-> **Batch-boundary `complete` (must be absorbed, never closes the stream)**: when a root session drains a queue of multiple messages, the server runs N merged turns and emits an internal `complete` with `batchBoundary: true` between rounds (see [session.md](session.md#message-queue-and-drain)). The SSE generators in `channels/web/handler.ts` flush the just-finished round's text on a `batchBoundary` complete but **do not** send a `complete` SSE frame and **do not** set `done` — the response stays open for the next round; only the **terminal** (unmarked) `complete` closes the HTTP stream. Without this guard a producer→sub-agent fan-out would truncate the web client after the first round. The `batchBoundary` flag is therefore an internal server-side event marker only — it is never serialized into the SSE payload a client sees, so a custom frontend just consumes one ordinary `complete` at the end. (ACP rides on this channel, so it inherits the same safe behavior.)
+> **Batch-boundary `complete` (must be absorbed, never closes the stream)**: when a root session drains a queue of multiple messages, the server runs N merged turns and emits an internal `complete` with `batchBoundary: true` between rounds (see [session.md](session.md#message-queue-and-drain)). The SSE generators in `channels/web/handler.ts` (`listenSession().events()` plus the `createMediaBuffer()` event processor) flush the just-finished round's text on a `batchBoundary` complete but **do not** send a `complete` SSE frame and **do not** set `done` — the response stays open for the next round; only the **terminal** (unmarked) `complete` closes the HTTP stream. Without this guard a producer→sub-agent fan-out would truncate the web client after the first round. The `batchBoundary` flag is therefore an internal server-side event marker only — it is never serialized into the SSE payload a client sees, so a custom frontend just consumes one ordinary `complete` at the end. (ACP rides on this channel, so it inherits the same safe behavior.)
+
+> **Listener lifetime**: `handleMessage` registers its session listener (`listenSession`) *before* the media save and `sendUserMessage` — it must be listening when the turn starts — and wraps everything from there to the end of `events()` in a `try/finally` that closes it. So a throw in between (media save failed, `sendUserMessage` threw), a `queued` result, or the end of the stream all drop the listener; before, only `events()`'s own finally and the `queued` branch did, and an early throw leaked it for the process lifetime. The unsubscribe is idempotent, so closing twice on the normal path is harmless. The route passes the request's abort signal (`c.req.raw.signal`) through to `events(signal)` — for `/web/chat` and a skill command's follow-on stream, as `/web/subscribe` already did — so a client that disconnects mid-turn ends the stream and drops the listener right away instead of at the turn's terminal `complete`. The turn itself keeps running; disconnecting is not `/web/stop`.
 
 #### Per-request overrides (`workspace`, `sessionId`, `agentId`)