@turmind/halo 0.1.9

package/bundled-docs/design/architecture.md

@@ -0,0 +1,270 @@
+# Backend Architecture
+
+> Drawn from the actual code, not a design brief. Use it to assess module coupling and responsibility boundaries.
+
+## Global topology
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         index.ts (entry)                            │
+│  Create Hono app → mount routes → start HTTP server → upgrade WS    │
+│                                                                     │
+│  Owned instances:                                                   │
+│    registry: SessionManagerRegistry                                 │
+│    channelDb: ChannelDb (~/.halo/secrets/channels/channels.db)     │
+│    wss: WebSocketServer                                             │
+│                                                                     │
+│  Route mounts (direct):                                             │
+│    /api/auth/*        → createAuthRoutes()                          │
+│    /api/files/*       → createFileRoutes()                          │
+│    /api/fs/*          → createFileRoutes (home/exists/browse/resolve)│
+│    /api/agent-configs/*→ createAgentConfigRoutes()                  │
+│    /api/skills/*      → createSkillRoutes()                         │
+│    /api/settings/*    → createSettingsRoutes()                      │
+│    /api/evolution/*   → createEvolutionRoutes()                     │
+│    /api/cron/*        → createCronRoutes()                          │
+│    /api/sessions/*    → createSessionRoutes()                       │
+│    /api/show/*        → createShowRoutes() (halo-city snapshot)     │
+│    /api/commands      → createCommandRoutes()                       │
+│  Route mounts (via bootChannels — registry-driven):                 │
+│    /api/web/*         (web descriptor)                              │
+│    /api/telegram/*    (telegram descriptor)                         │
+│    /api/weixin/*      (wechat descriptor)                           │
+│    /api/slack/*       (slack descriptor)                            │
+│    /api/feishu/*      (feishu descriptor)                           │
+│    /ws                → setupWebSocketHandler({wss,registry})       │
+│    /*                 → static frontend (Next.js out/)              │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Key modules
+
+### SessionManager — the central hub
+
+Manages the full lifecycle of every agent session (root + sub-agent). Each session is 1:1 with a `ModelRuntime` instance (provider-agnostic, see below). See [design/session.md](session.md) and [design/agent.md](agent.md).
+
+Depends directly on 10+ modules: ModelRuntime / Database / SessionStore / UILogBuilder / AgentLoader / MdLoader / WorkspaceTools / ConversationRepair / Compact / Config.
+
+Responsibilities:
+1. Agent instance lifecycle (create / restore / release)
+2. Session state machine (idle / running / compacting)
+3. Message routing (user→agent / agent→agent)
+4. The turn-execution loop + compaction
+
+Five concerns were split into their own files (SessionManager keeps thin pass-throughs and owns the instances, each taking `this` as host): **SessionUIStore** — UIState reducer + persistence + event dispatch (`emitEvent` → listener); **SessionQueryStore** — read-only session-metadata queries + the row→SessionInfo status projection; **SessionAgentBuilder** — agent.yaml → ModelRuntime + system prompt + tools + /context metadata; **SessionSkillCommands** — skill-backed slash-command permission resolution; **SessionStateStore** — `rawMessages` disk persistence (save/load agent state). See below.
+
+### ModelRuntime — LLM interaction layer (provider-agnostic)
+
+Files: `agents/model-runtime.ts` (interface + dispatcher), `agents/bedrock-agent.ts` (the `aws-bedrock-claude-invoke` implementation).
+
+**Interface**:
+
+```ts
+interface ModelRuntime {
+  messages: AnthropicMessage[]
+  run(input, opts?): AsyncGenerator<AgentEvent>
+}
+createModelRuntime(providerId: string, cfg: ModelRuntimeConfig): ModelRuntime
+```
+
+**Dispatch**: `agent.yaml`'s `model.provider` is looked up against `~/.halo/global/models/<providerId>.yaml`; the dispatcher's switch instantiates the matching implementation.
+
+**Modality capabilities**: Each model in the manifest declares `capabilities.image` / `capabilities.video` / `capabilities.audio` (boolean). SessionManager checks `modelSupportsImage()` at session creation in two places: (1) `createWorkspaceTools()` is passed `supportsVision` so the `view_image` tool is dropped from the tool list when the model can't ingest vision blocks — no exposed tool, no errant call, no provider 400; (2) user-supplied images on inbound messages are stripped at `buildInput()` with a text notice. Query functions: `config.ts` exports `modelSupportsImage()` / `modelSupportsVideo()` / `modelSupportsAudio()`.
+
+**Current providers**:
+- `aws-bedrock-claude-invoke` → `BedrockAgent` (uses the Bedrock InvokeModel API, non-streaming)
+
+**Adding a new provider**:
+1. Add a manifest at `models/<providerId>.yaml` (include modality flags)
+2. Add a case in `model-runtime.ts` returning your runtime class
+3. Implement `callModel()` (returns `Promise<ModelCallResult>`) and maintain `messages`
+
+**Core loop** (`AgentLoop.run()`, shared by all providers):
+1. Append the user message to `messages`
+2. `callModel()` → invoke the provider API (non-streaming), get complete response
+3. Yield `thinking` / `text` / `usage` / `tool_call` events
+4. `stop_reason=tool_use` → execute tools, yield `tool_result` events → loop
+5. Otherwise yield a `stop` event and return
+
+State: `messages: AnthropicMessage[]` (the full conversation history; external code can mutate it for compact/repair).
+
+### WebSocket Handler — real-time transport layer
+
+File: `ws/handler.ts`. See [design/ws.md](ws.md).
+
+One `ConnectedClient` per WS connection, holding: `sessionManager` / `agentSessionId` / `terminalManager` / `fileWatcher` / `backgroundSaves`. UI state (messageLog / streamBuffer / tokens) belongs to SessionManager's `UIState`, not the client.
+
+Message dispatch:
+- `chat` / `chat:stop` / `subscribe` / `session:clear` / `session:delete` → handled directly in `ws/handler.ts`
+- `command:*` → `dispatchCommand` (`channels/shared/commands.ts`) — same dispatcher every channel uses
+- `terminal:*` → TerminalManager
+
+### EventProcessor — event translation
+
+File: `ws/event-processor.ts` (pure functions).
+
+`sendWsNotification(event, state, turnId, ctx)` — converts OrchestratorEvent into a WS JSON message and sends it. Called *after* `applyEvent` has already mutated UIState. Does NOT mutate state itself. `bufferDetachedNotification(event, pendingEvents)` is the offline equivalent that buffers structural events for replay.
+
+### Broadcast — cross-client server-pushed events
+
+File: `ws/broadcast.ts`. Per-client `sendJson` is for chat-stream events that belong to one socket; `broadcast(event)` fans an event out to *every* connected admin client. Used for shared-state changes that any tab/browser cares about: evolution run state transitions, cron job/run state, channel binding changes. Replaces the `setInterval(fetch, ...)` polling pattern that earlier admin views used to detect server-side changes.
+
+`setBroadcastWss(wss)` is called once at server boot from `index.ts`; modules then `import { broadcast }` without threading the wss handle through. Callers that emit:
+
+- `evolution/ticker.ts` — diffs db status against an in-memory snapshot every 30s, emits `evolution:run_changed` / `evolution:apply_changed` for wrapper-driven transitions (the wrapper child can't reach the parent's wss directly)
+- `routes/evolution.ts` — REST mutations (approve/reject/retry) emit immediately so user-action latency is "instant"
+- `cron/runner.ts` — `runJob` insert + `finalize` emit `cron:run_changed`; `reconcileFromDb` emits `cron:job_changed kind=reconciled|deleted` for out-of-band db edits (e.g. the cron skill writing the db directly)
+- `routes/cron.ts` — REST mutations emit `cron:job_changed kind=created|updated|deleted` immediately
+
+### UILogBuilder — UI state reducer
+
+File: `sessions/ui-log-builder.ts` (pure functions).
+
+`applyEvent(state, event) → ApplyResult` is the core reducer. No I/O, no WS — callers decide when to persist.
+
+UIState fields: `messageLog` / `streamBuffer` / `contextTokens` / `outputTokens` / `subSessionLogs` / `turnToolCalls` / `turnContentBlocks` / ...
+
+### SessionUIStore — UI-log state + event routing
+
+File: `agents/session-ui-store.ts`. The stateful host around UILogBuilder, split out of SessionManager. Owns the per-root-session UIState map, the debounced persist timers, and the event-listener registry; drives `applyEvent` and decides flush-vs-debounce. SessionManager constructs it with `this` as the `SessionUIStoreHost` (db / workspaceRoot / in-memory session lookup / delete tombstone / the single tombstone-honouring `persistSessionFile`) and exposes same-named thin pass-throughs so external callers stay unchanged. Dependency is one-directional: store → host, never the reverse.
+
+### SessionQueryStore — read-only session-metadata queries
+
+File: `agents/session-query-store.ts`. Stateless; split out of SessionManager alongside SessionUIStore. Owns `listSessions` / `listDescendants` / `findLatestByPrefix` / `getSessionById` / `getSessionTree` and the `toSessionInfo` projection. All SQLite reads plus one cross-read: status derivation fuses the row's `stopped_at`, the in-memory run map (`promise !== null` ⇒ running), and a batched active-child lookup — in that precedence. Takes `this` as `SessionQueryStoreHost` (db / workspaceRoot / in-memory session lookup); SessionManager keeps same-named pass-throughs so the 20+ `getSessionById` callers and the `SessionManagerInternals` contract are unchanged.
+
+### SessionAgentBuilder — agent construction pipeline
+
+File: `agents/session-agent-builder.ts`. Stateless. Turns an agentId + agent.yaml into a live ModelRuntime plus system prompt, tool set, context/thinking config, and `/session context` metadata (`AgentMeta`/`BuiltAgent` are defined + exported here). `createSession` / `ensureSession` / the rerun paths call `buildAgentInstance`. Host surface: workspaceRoot / db / `createSessionTools`.
+
+### SessionSkillCommands — skill-command permissions
+
+File: `agents/session-skill-commands.ts`. Stateless, pure reads. Resolves which skill-backed slash commands an agent may invoke (yaml `skills:` whitelist ∩ not-disabled ∩ access gate via SKILL.md `requiresAccess`). Source of truth for the slash-suggest popup and the server-side check in `execSkillCommand`. Host surface: workspaceRoot / db.
+
+### SessionStateStore — rawMessages disk persistence
+
+File: `agents/session-state-store.ts`. Stateless. Saves/loads an agent's `rawMessages` (LLM-facing history) to its `.json` file via read-merge-write — the `rawMessages` half of session persistence (SessionUIStore owns the UI-log half; both write the same file). `saveAgentState` takes a narrow `SavableSession` (6 fields), not the full AgentSession. Host surface: workspaceRoot + `isSessionDeleted` (the tombstone short-circuit so a late save can't resurrect a deleted file).
+
+## Helper modules
+
+### SessionStore — disk persistence
+File: `sessions/session-store.ts`. Path: `.halo/sessions/{agentId}/{sessionId}.json`. Format described in [design/storage.md](storage.md).
+
+### AgentLoader — agent config loader
+File: `agents/agent-loader.ts`. `loadAgentYaml(agentId, wsRoot)` loads with workspace > global precedence.
+
+### MdLoader — prompt assembly
+File: `prompts/md-loader.ts`. See [design/prompt-system.md](prompt-system.md).
+
+### WorkspaceTools — agent tool set
+File: `tools/workspace-tools.ts`. 9 tools: file_read / view_image / file_write / file_edit / file_list / shell_exec / grep / glob / web_fetch. See [dev/tools.md](../dev/tools.md).
+
+### BackgroundHandler — post-disconnect event buffer
+File: `ws/background-handler.ts`. After WS disconnect it takes over events and buffers structural events for replay on reconnect.
+
+### WorkspaceWatcher — file watching
+File: `ws/file-watcher.ts`. chokidar → 300ms debounce + per-path Map dedup → callback. Ignores node_modules / .git / .next / dist. `.halo/sessions/` and `.halo/logs/` are **not** ignored — the dedup keeps volume low, and the front-end drops `change` events for files not open in the editor, so Explorer can reflect session deletions/creations while chat streaming stays cheap.
+
+### TerminalManager — PTY management
+File: `ws/terminal-manager.ts`. Spawns a shell via node-pty. On disconnect, detaches with a 50KB ring buffer; replays on reconnect.
+
+### Self-Evolution — workspace prompt-tuning loop
+Files: `evolution/{ticker,evo-wrapper,enqueue,spawn,archive}.ts`, `db/evo-db.ts`, `routes/evolution.ts`. Internal agents `__evo_agent__` / `__score__` / `__apply_agent__` (in `templates/agents/`) drive a 12-phase orchestration: snapshot → evo drafts → wrapper dry-runs → scorer grades → reviewer approves → apply agent merges → wrapper history-snapshots + cps to main. Per-task wrapper Node child process owns all sub-cli calls; ticker is stateless and lives in the server. State in `~/.halo/global/evo.db`. See [plans/self-evolution.md](../plans/self-evolution.md).
+
+## REST routes
+
+See [dev/api.md](../dev/api.md).
+
+## @turmind/halo-cli package
+
+Standalone terminal client — imports agent-core modules from `@turmind/halo-server` via subpath exports, bypassing all HTTP/WS infrastructure.
+
+Entry: `packages/cli/src/index.ts` → `harness.ts` (wraps SessionManager) → `cli.ts` (non-interactive) / `tui.ts` (interactive readline).
+
+Uses `dispatchCommand()` from `channels/shared/commands.ts` for `/session new`, `/session list`, `/session switch`, `/session compact`, etc. Session prefix: `cli_`. Sessions are persisted identically to admin/channel sessions and are visible in the admin panel.
+
+See [guide/cli.md](../guide/cli.md).
+
+## @turmind/halo-core package
+
+### Workspace (`core/src/workspace/workspace.ts`)
+Methods: `init(name)` / `readFile(path)` / `writeFile(path, content)` / `listFiles(dir?, recursive?)` / `fileExists(path)` / `validatePath(path)` (path-traversal check).
+
+### GitManager (`core/src/workspace/git-manager.ts`)
+Methods: `init(dir)` / `commitAll(dir, msg)` / `getDiff(dir, path)`. Backed by simple-git.
+
+## Dependency matrix
+
+```
+                        │ SM │ WS │ EP │ BG │ Routes │ Core │ CLI │
+─────────────────────────┼────┼────┼────┼────┼────────┼──────┼─────┤
+ModelRuntime            │ ✦  │    │    │    │        │      │     │
+SessionManager          │    │ ✦  │    │    │        │      │ ✦   │
+SessionUIStore          │ ✦  │    │    │    │        │      │     │
+SessionQueryStore       │ ✦  │    │    │    │        │      │     │
+SessionAgentBuilder     │ ✦  │    │    │    │        │      │     │
+SessionSkillCommands    │ ✦  │    │    │    │        │      │     │
+SessionStateStore       │ ✦  │    │    │    │        │      │     │
+EventProcessor          │    │ ✦  │    │ ✦  │        │      │
+UILogBuilder            │ ✦  │    │    │    │        │      │
+SessionStore            │ ✦  │ ✦  │ ✦  │ ✦  │ ✦(Ses) │      │
+AgentLoader             │ ✦  │    │    │    │ ✦(AC)  │      │
+MdLoader                │ ✦  │    │    │    │ ✦(AC)  │      │
+WorkspaceTools          │ ✦  │    │    │    │        │      │
+ConversationRepair      │ ✦  │    │    │    │        │      │
+Compact                 │ ✦  │    │    │    │        │      │
+Config                  │ ✦  │ ✦  │    │    │ ✦      │      │ ✦   │
+Database                │ ✦  │ ✦  │    │    │ ✦      │      │     │
+Workspace               │    │    │    │    │ ✦(F)   │      │
+GitManager              │    │    │    │    │ ✦(F)   │      │
+WorkspaceWatcher        │    │ ✦  │    │    │        │      │
+TerminalManager         │    │ ✦  │    │    │        │      │
+BackgroundHandler       │    │ ✦  │    │    │        │      │
+```
+
+## Storage responsibility
+
+SQLite only holds metadata indexes; all content lives on the filesystem.
+
+| Medium | Writer | Contents |
+|---|---|---|
+| SQLite `sessions` | SessionRoutes, WS handler | Frontend session metadata |
+| SQLite `agent_sessions` | SessionManager | Agent session metadata (root + children; includes `working_dir` and `access_level` columns) |
+| `.halo/sessions/{agentId}/{sid}.json` | SessionManager, SessionStore | Session messages |
+| `.halo/sessions/{agentId}/{sid}.events.jsonl` | SessionManager | Event audit log |
+| `.halo/agents/{id}/agent.yaml` | AgentConfigRoutes | Agent YAML (workspace scope) |
+| `.halo/agents/{id}/AGENT.md` | AgentConfigRoutes | Agent personality |
+| `~/.halo/global/agents/{id}/agent.yaml` | AgentConfigRoutes | Agent YAML (global scope) |
+| `.halo/skills/{id}/SKILL.md` | SkillRoutes | Skill definition (workspace scope) |
+| `~/.halo/global/skills/{id}/SKILL.md` | SkillRoutes | Skill definition (global scope) |
+| `~/.halo/secrets/settings.yaml` | SettingsRoutes | Global settings |
+| `<project>/.halo/settings.yaml` | SettingsRoutes | Per-project overrides |
+| `~/.halo/global/models/<provider>.yaml` | Manual edit | Model registry — one file per provider, scanned at startup, used to dispatch to the matching runtime |
+| `~/.halo/global/prompts/{bootstrap,all,root}/*.md` | init.ts seed + user | System prompts |
+| `~/.halo/logs/server.log` or `<ws>/.halo/logs/server.log` | Logger | Server logs (10 MB rotation) |
+| `~/.halo/secrets/channels/channels.db` | All channels | Unified channel accounts (Telegram, Web, WeChat) — see [storage.md](storage.md#channel_accounts) |
+
+## Coupling hot spots
+
+**SessionManager (~2260 lines)** — the central hub. Five concerns were carved out into one-directional sibling classes (see Key modules): UI-log/events (SessionUIStore), metadata queries (SessionQueryStore), agent construction (SessionAgentBuilder), skill-command permissions (SessionSkillCommands), rawMessages persistence (SessionStateStore). The carve-out is **complete** — what remains is the genuine high-cohesion core, all bound to the `sessions: Map` mutable state: the turn-execution loop, session lifecycle, the concurrency guards (`locks` init-mutex + `deletedSessionIds` delete-tombstone), and compaction.
+
+Compaction stays in, by deliberate decision at two levels. Cluster-level: it's bidirectionally interwoven with the turn loop (a beforeCallModel hook that itself runs a turn) and mutates shared per-session state, so extraction would widen the host interface and tangle control flow. Function-level: `selfCompactSession` is one connected chain (compute cut → summarize via LLM → rebuild `[summary+recent]` → write back) — pulling the pure bits into compact.ts would sever a coherent single-use method and scatter it across files, trading cohesion for testability. A long, single-purpose, sequentially-coupled method is fine; the inherent complexity of session handling doesn't shrink by relocating it.
+
+**Medium: WS Handler** — depends on SessionManager for all agent operations, owns connection lifecycle, compact orchestration, session switching, terminal/file watcher. It used to have two-way state sync with SessionManager (resolved: UIState now belongs to SessionManager).
+
+**Low: REST Routes / Core / tools** — no cross-dependencies; interact via DB or filesystem.
+
+**Dual writes**: Session data lives in both SQLite and the on-disk JSON; deletion must synchronise all three (SQLite → JSON → JSONL).
+
+## Frontend (short version)
+
+```
+packages/admin
+├── Next.js 15 static export → out/ → served by Hono
+├── Talks to the backend via REST + WebSocket
+└── No SSR, pure client SPA
+```
+
+Code structure:
+- `app/` — Next.js app router entry
+- `features/` — UI modules grouped by domain (agents / chat / editor / explorer / terminal / workspace / settings / skills / auth)
+- `shared/` — cross-feature resources (stores / components / ws-handlers / ws-client / api-client / types / utils)

package/bundled-docs/design/background-dispatch.md

@@ -0,0 +1,151 @@
+# Background Session Event Dispatch
+
+When the user hits `/session new` while a sub-agent is still running — the old session's agent has to stay alive, its events have to be routed to the right session file, and the user has to see everything seamlessly when they switch back.
+
+## Problem
+
+SessionManager emits events through a per-tree event listener system (`eventListeners: Map<rootId, Set<handler>>`). The WS handler converts events into WS messages for the frontend. When the user hits `/session new`:
+- A new session starts (fresh conversation)
+- The old session's agent may still be running
+- Old-session events **must not** leak into the new session
+- Events must persist to the old session's file
+- Switching back should show the full history
+
+## Architecture
+
+### Event flow layers
+
+```
+SessionManager.emitEvent(sessionId, event)
+  ├─ appendEventLog(sessionId, event)         ← JSONL audit trail
+  ├─ reduceIntoUIState(rootId, event)         ← updates UIState (messageLog, tokens, etc.)
+  └─ eventListeners.get(rootId) → forEach(listener(event, state, turnId))
+```
+
+**Key detail**: `emitEvent` first mutates the UIState via `reduceIntoUIState`, then calls listeners with the *pre-mutation* `turnId`. Listeners receive already-applied state — they do NOT mutate state themselves.
+
+### Three event handler states
+
+| State | Listener | Events go to |
+|---|---|---|
+| **Connected** | `registerEventListener(rootId, handler)` | `sendWsNotification(event, state, turnId, ctx)` → WS JSON |
+| **Background** (after `/session new`) | Inline `bufferDetachedNotification` closure | `pendingEvents[]` (structural events only for later replay) |
+| **Detached** (WS disconnect) | Same `bufferDetachedNotification` pattern | `pendingEvents[]` on `DetachedSession` |
+
+State is NOT duplicated — all handlers read from `SessionManager.getUIState(rootId)`.
+
+## `/session new` (session:clear) flow
+
+Source: `packages/server/src/ws/handler.ts` (`session:clear` case)
+
+```
+User clicks /session new
+    │
+    ▼
+session:clear handler
+    │
+    ├─ ctx.saveSession()                     ← persist current UIState to file
+    │
+    ├─ create inline bgHandler:
+    │     (event, state, turnId) => bufferDetachedNotification(event, pendingEvents)
+    │
+    ├─ sm.registerEventListener(agentSessionId, bgHandler)
+    │     ← old session's future events go to the buffer
+    │
+    ├─ backgroundSaves.set(prevSessionId, () => ctx.saveSession())
+    │     ← register a save fn for when user switches back or disconnects
+    │
+    ├─ reset client state (agentSessionId=null, sessionId=null)
+    └─ send { type: 'session:cleared' }
+```
+
+### `createBackgroundHandler` (utility)
+
+Location: `packages/server/src/ws/background-handler.ts`
+
+A helper used in contexts outside session:clear (e.g. detached sessions). Takes 3 args:
+
+```typescript
+createBackgroundHandler(sessionId: string, projectPath: string | null, sm: SessionManager)
+→ { handler, save, pendingEvents }
+```
+
+- **handler**: `(event, state, turnId) => bufferDetachedNotification(event, pendingEvents)` — buffers structural WS events
+- **save**: reads live UIState from `sm.getUIState(sessionId)`, creates a snapshot, writes to file
+- **pendingEvents**: array of buffered structural events for replay on reconnect
+
+The handler does NOT hold its own messageLog/streamBuffer/tokenState. All state lives in SessionManager's UIState, maintained by `reduceIntoUIState → applyEvent`.
+
+### When save fires
+
+Background state persists in three scenarios:
+
+1. **`backgroundSaves.get(sessionId)?.()` in subscribe** — user switches back to the old session; called before re-attaching the listener
+2. **`backgroundSaves` flush on disconnect** — WS closes, flush every pending bg
+3. **Periodic auto-save by UIState reducer** — `complete`, `tool_call`, `tool_result`, `usage` events trigger save via the reducer
+
+## Subscribe (switching back) flow
+
+```
+User clicks old session in sidebar
+    │
+    ▼
+Frontend: { type: 'subscribe', sessionId: oldId, projectId }
+    │
+    ▼
+subscribe handler
+    │
+    ├─ if switching session → saveSession(current)
+    │
+    ├─ backgroundSaves.get(sessionId)?.()  ← flush bg state to disk
+    │     backgroundSaves.delete(sessionId)
+    │
+    ├─ re-attach the event listener to this session tree
+    │     (replaces the bg buffer handler with the live WS handler)
+    │
+    ├─ Load UIState from SessionManager (or from file if not in memory)
+    │
+    └─ Send state:snapshot carrying the full messageLog
+```
+
+## When disconnect happens while background is still running
+
+```
+disconnect handler
+    │
+    ├─ (if agent running) → detach session with bufferDetachedNotification
+    ├─ (otherwise)        → saveSession
+    │
+    └─ flush every backgroundSaves
+          for (const [sid, saveFn] of backgroundSaves)
+            saveFn()
+```
+
+## Relevant files
+
+| File | Relevant code |
+|---|---|
+| `packages/server/src/ws/background-handler.ts` | `createBackgroundHandler()` utility |
+| `packages/server/src/ws/handler.ts` | `session:clear` case — inline bgHandler + `backgroundSaves` registration |
+| `packages/server/src/ws/event-processor.ts` | `sendWsNotification()`, `bufferDetachedNotification()` |
+| `packages/server/src/agents/session-manager.ts` | `emitEvent()`, `reduceIntoUIState()`, `registerEventListener()` |
+| `packages/server/src/sessions/ui-log-builder.ts` | `applyEvent()`, `createSaveSnapshot()`, UIState type |
+| `packages/server/src/sessions/session-store.ts` | `saveSessionToFile()`, `loadSessionMessages()` |
+
+## Historical bug fixes (2026-04-20/21)
+
+### 1. After `/session new`, sub-agent events routed to the wrong handler
+**Root cause**: old code captured `const onEvent = this.eventHandler` at session start. When the handler was replaced, already-running sub-agents still used the old reference.
+**Fix**: switched to `emitEvent()` which does a live lookup on `eventListeners.get(rootId)`. New listeners immediately receive events from running sub-agents.
+
+### 2. `client.messageLog` polluted by stale sub-agent events
+**Root cause**: before #1 was fixed, sub-agent events went through the live WS handler, pushing messages into the new session's state.
+**Fix**: (a) fixing #1 made event routing tree-scoped. (b) session:clear explicitly saves before switching and resets client state.
+
+### 3. `createBackgroundHandler` missing a return
+**Root cause**: the function defined `handler` and `save` locally but did not `return { handler, save }`.
+**Fix**: add `return { handler, save, pendingEvents }` at the end.
+
+### 4. Stream buffer not flushed before saveSession in session:clear
+**Root cause**: in-flight stream text wasn't captured before save.
+**Fix**: UIState reducer now incrementally persists on every structural event — stream text is folded into messageLog by `applyEvent` before save triggers.

package/bundled-docs/design/command.md

@@ -0,0 +1,58 @@
+# Command — Design
+
+Unified command processing layer — all channels (WS, WeChat, Telegram, Web, CLI/TUI) share a single dispatch path.
+
+## Architecture
+
+```
+Channel handlers          Shared layer                  SessionManager
+──────────────            ────────────                  ──────────────
+WS handler ─────┐
+WeChat handler ──┼──►  dispatchCommand()  ──────────►  SM methods
+Telegram handler ┤     (channels/shared/commands.ts)   (compact, create, delete, …)
+Web handler ─────┤
+CLI/TUI ─────────┘        │
+                           └── execSkillCommand()       (skill fallback)
+                               (commands/skill-command.ts)
+```
+
+WS handler special-cases `/session compact` because it needs UI progress callbacks: `compact` → `sm.compactSession(sid, { onProgress })` directly. Every other command routes through `dispatchCommand`.
+
+## Key modules
+
+| Module | File | Purpose |
+|---|---|---|
+| `dispatchCommand` | `channels/shared/commands.ts` | Single switch routing all slash commands to exec functions |
+| `CommandRegistry` | `commands/registry.ts` | Listing-only — stores `CommandDescriptor` for REST `/api/commands` discovery |
+| `scanSkillDescriptors` | `commands/skill-command.ts` | Scan skill dirs → return `CommandDescriptor[]` for registry |
+| `execSkillCommand` | `commands/skill-command.ts` | Execute a skill slash command (read SKILL.md, render, send to SM) |
+
+## Command dispatch flow
+
+1. Channel receives a slash command from user input (or WS `command:<name>` message)
+2. Channel builds a `CommandContext` (shared interface: sm, userId, sessionPrefix, accessLevel, workspacePath, lang)
+3. Channel calls `dispatchCommand(ctx, '/command', args)`
+4. `dispatchCommand` switch: `/help` and `/evo` call `exec*` directly; object commands (`/session`, `/agent`, `/skill`, `/workspace`) and the default case route through `routeObjectOrSkill`
+5. `routeObjectOrSkill` tries the builtin noun-verb table first (`SUBCOMMAND_ROUTES`, per-verb access via `verbAccessMap`), else falls through to `execSkillCommand` for the same-named skill — verb/permission model in [requirements/command.md](../requirements/command.md)
+6. Returns `CommandResult { text, switchTo?, workspace? }` — channel formats and sends to user
+
+`scanSkillDescriptors` drops skill commands that collide with a built-in (or another skill) at scan time, so dispatch and the discovery API stay consistent — see [requirements/command.md](../requirements/command.md#conflict-detection).
+
+## File structure
+
+```
+packages/server/src/commands/
+  types.ts           — CommandDescriptor interface
+  registry.ts        — CommandRegistry (listing-only, for REST discovery)
+  skill-command.ts   — scanSkillDescriptors() + execSkillCommand()
+  index.ts           — Registry singleton + built-in descriptor registration
+
+packages/server/src/channels/shared/
+  commands.ts        — dispatchCommand(), all exec* functions, CommandContext, CommandResult
+```
+
+## Frontend integration
+
+- `features/chat/slash-commands.ts` — `refreshCommands(projectId)` pulls from REST API and merges client-only fallbacks
+- `features/chat/use-chat.ts` — handles client-only commands locally; server commands sent as `command:<name>` via WS
+- `features/chat/chat-panel.tsx` — calls `refreshCommands()` on project switch

package/bundled-docs/design/cron.md

@@ -0,0 +1,88 @@
+# Cron — Scheduled Tasks Design
+
+Run an agent on a schedule (daily report, periodic broadcast) and fan the result out to channels. Jobs live in the global db, fire via [croner](https://github.com/hexagon/croner), and execute as a fresh `halo cli` child process.
+
+## Architecture
+
+```
+cron_jobs (global db)                      registered at boot:
+      │                                    ┌── slack/cron-dispatcher
+      ▼  reloadAll / reconcileFromDb       ├── feishu/cron-dispatcher
+  runner.ts ──── croner schedule ──┐       ├── telegram/cron-dispatcher
+      │                            │       └── wechat/cron-dispatcher
+      │ fire                       │              ▲
+      ▼                            │              │ registerCronDispatcher
+  spawn `halo cli -n -s cron-<id>` │       dispatcher.ts (registry)
+      │ stdout                     │              ▲
+      ▼                            └──────────────┘ dispatchToTargets(text, targets)
+  cron_runs (audit row + log file) ───────────────┘
+```
+
+Two halves, cleanly split:
+- **runner.ts** — the scheduler. Owns the croner instances, spawns the cli, persists audit rows.
+- **dispatcher.ts** — a channel-agnostic registry. Knows how to look up a dispatcher by `channelType` and hand off; knows nothing about any specific channel.
+
+## Scheduling model
+
+Schedules are **durable** — the source of truth is the `cron_jobs` table; in-memory croner state is rebuilt on every server boot (`startCronDaemon` → `reloadAll`). A restart never loses a schedule.
+
+- **Recurring**: standard cron expression (`job.schedule`), optional `timezone`.
+- **One-shot**: `job.runAt` (epoch ms) — croner fires once at that instant. After it completes, `finalize` sets `enabled=0` so it never re-fires. A `runAt` already in the past at schedule time is marked `lastRunStatus='missed'` and disabled (rather than firing immediately or retrying every reconcile).
+
+### Hot-reload + out-of-band edits
+
+REST route mutations call `scheduleJob` / `unscheduleJob` directly. But the `cron` skill (and manual ops) edit `cron.db` over a *different* sqlite connection. `reconcileFromDb` (10s timer) catches those:
+
+- Fast path: `PRAGMA data_version` flips only when *another* connection commits. If unchanged since last pass, skip the full select entirely — one pragma read (~µs) vs. a select-all + per-row fingerprint compare.
+- On change: diff db rows against the in-memory `_fingerprint` map (`enabled|schedule|runAt|timezone`); schedule new rows, unschedule deleted ones, re-instantiate croner only for rows whose fingerprint changed. Broadcasts a coalesced `cron:job_changed` per affected job.
+
+## Execution (`runJob`)
+
+Each fire:
+
+1. **Concurrency guard**: if the same `jobId` is already running in this process (in-memory `_inflight` set), insert a `cron_runs` row with `status='skipped'`, `failureReason='previous run still in progress'`, broadcast, and bail without spawning. Applies to both scheduled fires and manual run-now clicks. Two overlapping cli children would double-write the same `cron-<jobId>` on-disk session state; SessionManager's per-session lock is in-process and can't see across cli children, so this set is the cheapest place to enforce serialization. Lost on server restart by design — no stale-entry cleanup needed.
+2. Insert a `cron_runs` row with `status='running'` up front (UI sees it mid-flight); broadcast `cron:run_changed`.
+3. Check `job.workspacePath` exists — fail loudly if the workspace was moved/deleted.
+4. Spawn `halo cli -a <agent> -s cron-<jobId> -w <workspace>`, prompt on **stdin** (avoids Windows argv length limits). The stable `cron-<jobId>` session id means each fire *resumes the same session*, so the conversation accumulates and is reviewable in the admin Sessions tab.
+5. Tee stdout + stderr live to `~/.halo/global/logs/cron/<runId>.log`; capture stdout to memory for dispatch.
+6. Enforce a **3600s timeout** via a Node timer (kills child, reports exit code 124 — cross-platform, not the Linux-only `timeout(1)`). Generous because overlap-of-the-same-job is already blocked up-front in step 1; this is just the long-stop reaper for a truly stuck child.
+7. Classify: exit 124 → `timeout`; non-zero → `failed`; zero but empty stdout → `failed` ("nothing to dispatch"); else `succeeded`.
+8. On success only, `dispatchToTargets(stdout, targets)`. If every target fails, downgrade to `failed`.
+9. `finalize`: write the terminal `cron_runs` row, update `cron_jobs.lastRun*`, disable one-shot jobs, broadcast. The `_inflight` entry is released in `finally`, regardless of outcome.
+
+The cli executable is resolved via `resolveHaloCli()` (`$HALO_CLI` override; `halo.cmd` on Windows to dodge the GUI `Halo.exe` on PATH).
+
+## Dispatch model
+
+`dispatcher.ts` is a registry keyed by `channelType`. Each channel ships a `CronChannelDispatcher` inside its own directory and calls `registerCronDispatcher(...)` once at boot — **adding a channel never edits dispatcher.ts**.
+
+```ts
+interface CronChannelDispatcher {
+  channelType: string
+  dispatch: (accountId, text, chatId?) => Promise<DispatchResult[]>
+  listTargets?: () => CronTargetOption[]
+}
+```
+
+- `dispatchToTargets` is **never throws** — every target's outcome (ok / error) is captured into a `DispatchResult[]` persisted to `cron_runs.dispatch_results`. One channel being down doesn't block the others.
+- **`chatId` semantics**: when a job is created from inside a chat, the target pins to that conversation (`chatId` set). When unset, the channel's own fan-out / default-recipient logic decides (e.g. Telegram fans out to its whitelist; Slack/Feishu require an explicit `chatId`).
+- `listTargets()` aggregates across all dispatchers (`listAllCronTargets`) to feed the admin create-form dropdown without the routes knowing any channel.
+
+## Retention
+
+- **Runs**: keep newest `RUNS_PER_JOB_KEEP` (100) rows per job; older pruned on each new run via a single `DELETE … NOT IN (SELECT … LIMIT 100)` over the `(job_id, started_at)` index.
+- **Logs**: files older than 30 days deleted on a daily timer (db row kept; UI shows "log unavailable"). `cron_runs` rows older than 60 days are also dropped.
+
+## Key files
+
+- `packages/server/src/cron/runner.ts` — scheduler: croner lifecycle, `runJob` spawn/capture/finalize, reconcile, retention.
+- `packages/server/src/cron/dispatcher.ts` — channel-agnostic dispatch registry (`registerCronDispatcher`, `dispatchToTargets`, `listAllCronTargets`).
+- `packages/server/src/db/cron-db.ts` — `cron_jobs` + `cron_runs` schema, `getCronDb`.
+- `packages/server/src/channels/<ch>/cron-dispatcher.ts` — per-channel `dispatch` + `listTargets`.
+- `packages/server/templates/skills/cron/SKILL.md` — the agent-facing skill that CRUDs `cron_jobs` (edits the db directly; `reconcileFromDb` picks it up).
+
+## Scope
+
+Supported: recurring (cron expr) + one-shot (`runAt`) schedules; per-timezone; multi-target fan-out; stable accumulating session per job; run-now (manual trigger); admin UI history with per-run logs + dispatch results.
+
+Not supported: sub-minute schedules below croner's resolution; in-process job execution (always a fresh cli child); conversation context carried *between different jobs* (each job has its own `cron-<jobId>` session).