@turmind/halo 1.5.3-alpha → 1.5.5

package/bundled-docs/design/architecture.md

@@ -17,14 +17,20 @@
 │  Route mounts (direct):                                             │
 │    /api/auth/*        → createAuthRoutes()                          │
 │    /api/files/*       → createFileRoutes()                          │
+│    /api/data-preview/*→ createDataPreviewRoutes()                   │
+│    /api/git/*         → createGitRoutes()                           │
 │    /api/fs/*          → createFileRoutes (home/exists/browse/resolve)│
 │    /api/agent-configs/*→ createAgentConfigRoutes()                  │
 │    /api/skills/*      → createSkillRoutes()                         │
 │    /api/settings/*    → createSettingsRoutes()                      │
 │    /api/evolution/*   → createEvolutionRoutes()                     │
 │    /api/cron/*        → createCronRoutes()                          │
+│    /api/extensions/*  → createExtensionRoutes()                     │
 │    /api/sessions/*    → createSessionRoutes()                       │
+│    /api/sessions/logs/:id/archive/:n → createSessionArchiveRoutes() │
 │    /api/show/*        → createShowRoutes() (halo-city snapshot)     │
+│    /api/metrics       → createMetricsRoutes()                       │
+│    /api/health        (inline in index.ts)                          │
 │    /api/commands      → createCommandRoutes()                       │
 │  Route mounts (via bootChannels — registry-driven):                 │
 │    /api/web/*         (web descriptor)                              │
@@ -32,8 +38,10 @@
 │    /api/wechat/*      (wechat descriptor)                           │
 │    /api/slack/*       (slack descriptor)                            │
 │    /api/feishu/*      (feishu descriptor)                           │
+│    /api/wecom/*       (wecom descriptor)                            │
 │    /ws                → setupWebSocketHandler({wss,registry})       │
 │    /*                 → static frontend (Next.js out/)              │
+│    /ping, /invocations → createAgentCoreRoutes() (agentcore mode)   │
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -74,7 +82,7 @@ createModelRuntime(providerId: string, cfg: ModelRuntimeConfig): ModelRuntime
 **Current providers**:
 - `aws-bedrock-claude-invoke` → `BedrockAgent` (uses the Bedrock InvokeModelWithResponseStream API — text / thinking chunks reach the UI as they are generated)
 - `anthropic` / `mimo-token-plan-china` → `AnthropicAgent`, `minimax` → `MiniMaxAgent`, `qwen` → `QwenAgent` (Anthropic Messages API over HTTP with `stream: true`; the SSE is folded by the same `AnthropicStreamAccumulator` as Bedrock via `fetchAnthropicStream` in `anthropic-stream.ts`, so they stream too)
-- The OpenAI-family (`openai` / `deepseek` / `kimi` / `zhipu` / `doubao` / `hunyuan`) → `chat/completions` over HTTP with `stream: true` + `stream_options.include_usage`; the `chat.completion.chunk` SSE is folded back into the non-streaming `choices[0].message` shape by `fetchChatCompletionStream` in `openai-chat-stream.ts` (a transport helper, not a base class — each agent keeps its own body / message conversion / usage math), so they stream too
+- The OpenAI-family (`openai` / `deepseek` / `kimi` / `zhipu` / `doubao` / `hunyuan`) → `chat/completions` over HTTP with `stream: true` + `stream_options.include_usage`; the `chat.completion.chunk` SSE is folded back into the non-streaming `choices[0].message` shape by `fetchChatCompletionStream` in `openai-chat-stream.ts` (a transport helper, not a base class; message/tool conversion and result parsing are shared via `openai-chat-format.ts`, while each agent keeps its own request body / thinking / usage math), so they stream too
 - Mantle (`aws-bedrock-mantle` / `aws-bedrock-openai`) → `MantleAgent`, OpenAI Responses API over HTTP with `stream: true`; `readResponsesStream` (module-level in `mantle-agent.ts`) reports `response.output_text.delta` frames live and takes the full final response object off the terminal `response.completed` / `response.incomplete` frame, so the existing `output[]` parse runs unchanged (bedrock-mantle sends no `[DONE]`, bedrock-runtime does — `readSseJson` skips it either way)
 - Every provider streams; the `onDelta` hook is still optional per provider, so a future non-streaming one just ignores it
 
@@ -107,11 +115,11 @@ Message dispatch:
 
 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.
+`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, sessionId)` 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.
+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, session list changes, goal state, preview extensions. 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:
 
@@ -119,6 +127,10 @@ File: `ws/broadcast.ts`. Per-client `sendJson` is for chat-stream events that be
 - `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
+- `agents/session-manager.ts` (root `createSession`), `agents/session-ui-store.ts` (root `complete`), `routes/sessions.ts` — `session:changed`
+- `agents/goal-mode.ts` — `goal:changed`
+- `extensions/watcher.ts` — `extension:changed` (full snapshot)
+- `routes/git.ts` — `broadcastToWorkspace` a `.git` `file:changed` so every socket on that workspace refreshes
 
 ### UILogBuilder — UI state reducer
 
@@ -146,7 +158,7 @@ File: `agents/session-skill-commands.ts`. Stateless, pure reads. Resolves which
 
 ### 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).
+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` (8 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
 
@@ -163,7 +175,7 @@ File: `prompts/md-loader.ts`. See [design/prompt-system.md](prompt-system.md).
 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).
 
 ### Detached event buffer — post-disconnect replay
-File: `ws/handler.ts` (`cleanupConnection`) + `bufferDetachedNotification` in `ws/event-processor.ts`. After WS disconnect, an inline handler takes over the session tree's events and buffers structural ones for replay on reconnect. A *cleared* session (`/session new`) gets no handler at all — see [design/background-dispatch.md](background-dispatch.md).
+File: `ws/handler.ts` (`cleanupConnection`) + `bufferDetachedNotification` in `ws/event-processor.ts`. After WS disconnect, an inline handler takes over the session tree's events and buffers structural ones for replay on reconnect. `/session new` only opens a draft tab — the previous session stays subscribed — see [design/background-dispatch.md](background-dispatch.md).
 
 ### WorkspaceWatcher — file watching
 File: `ws/file-watcher.ts`. `@parcel/watcher` recursive native subscription (one per workspace root, shared across connections via `ws/watcher-pool.ts`) → 300ms debounce + per-path Map dedup → callback. Ignores node_modules / .git / .next / dist etc. (`IGNORED_SEGMENTS`) — passed to parcel as the bare names (top-level `ignorePaths`, string compare) plus **one** `**/{a,b,…}/**` brace glob for nested occurrences. Not one glob per segment: parcel runs every ignore regex against every inode during the initial walk, and 52 separate regexes made subscribe on a ~26k-inode repo take ~13s (one brace regex: ~0.8s, same watch set). `.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.
@@ -172,7 +184,7 @@ File: `ws/file-watcher.ts`. `@parcel/watcher` recursive native subscription (one
 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).
+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 [evolution.md](evolution.md).
 
 ### Run ledger — restart nudge for interrupted roots
 Files: `agents/run-ledger.ts` (sweep + skip rules) + `db/runs-db.ts` (the global `~/.halo/global/runs.db` table `running_sessions`, same singleton pattern as `evo.db`/`cron.db`). `runSession` inserts its session id on entry and deletes it in the finally (server-only, gated on `reconcileOrphansOnBoot`), so whatever is left at boot is exactly what the previous process was mid-run on; the sweep drains those rows and nudges each interrupted root. `index.ts` runs this eagerly: right after constructing the `SessionManagerRegistry` and before `bootChannels`, it loops `listRunningWorkspaces()` and claims+builds a `SessionManager` for each one that isn't already owned by another live server, rather than waiting for someone to open the workspace. See [design/session.md](session.md#run-ledger--restart-nudge-for-interrupted-roots-halo-globalrunsdb).
@@ -185,7 +197,7 @@ See [dev/api.md](../dev/api.md).
 
 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).
+Entry: `packages/cli/src/index.ts` → `harness.ts` (wraps SessionManager) → `cli.ts` (non-interactive) / `tui.tsx` + `tui/` (interactive, ink/React).
 
 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.
 
@@ -233,10 +245,8 @@ 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) |
@@ -246,12 +256,12 @@ SQLite only holds metadata indexes; all content lives on the filesystem.
 | `<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) |
+| `~/.halo/global/logs/server.log` | Logger | Server logs (10 MB rotation) |
+| `~/.halo/secrets/channels/channels.db` | All channels | Unified channel accounts (Web, Telegram, WeChat, Slack, Feishu, WeCom) — 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.
+**SessionManager (~3350 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.
 
@@ -259,7 +269,7 @@ Compaction stays in, by deliberate decision at two levels. Cluster-level: it's b
 
 **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).
+**Dual writes**: Session data lives in both SQLite and the on-disk JSON; deletion must synchronise both (SQLite → JSON + archive segments).
 
 ## Frontend (short version)
 
@@ -272,5 +282,5 @@ packages/admin
 
 Code structure:
 - `app/` — Next.js app router entry
-- `features/` — UI modules grouped by domain (agents / chat / editor / explorer / terminal / workspace / settings / skills / auth)
+- `features/` — UI modules grouped by domain (agents / chat / editor / explorer / terminal / workspace / settings / skills / auth / source-control / cron / evolution / channels, plus one dir per channel)
 - `shared/` — cross-feature resources (stores / components / ws-handlers / ws-client / api-client / types / utils)

package/bundled-docs/design/command.md

@@ -1,6 +1,6 @@
 # Command — Design
 
-Unified command processing layer — all channels (WS, WeChat, Telegram, Web, CLI/TUI) share a single dispatch path.
+Unified command processing layer — all channels (WS, WeChat, Telegram, Slack, Feishu, WeCom, Web, CLI/TUI) share a single dispatch path.
 
 ## Architecture
 
@@ -32,9 +32,9 @@ WS handler special-cases `/session compact` because it needs UI progress callbac
 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`
+4. `dispatchCommand` switch: `/help` and `/evo` call `exec*` directly; object commands (`/session`, `/agent`, `/skill`, `/workspace`, `/goal` when goal mode is enabled) 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
+6. Returns `CommandResult { text, switchTo?, workspace?, startedTurn?, sessionId? }` — 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).
 
@@ -53,6 +53,6 @@ packages/server/src/channels/shared/
 
 ## Frontend integration
 
-- `features/chat/slash-commands.ts` — `refreshCommands(projectId)` pulls from REST API and merges client-only fallbacks
+- `features/chat/slash-commands.ts` — `refreshCommands(projectId, sessionId?, agentId?)` pulls from REST API; a client-side fallback list is used only when that fails
 - `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
+- `features/chat/chat-panel.tsx` — calls `refreshCommands()` on project / session / agent switch

package/bundled-docs/design/cron.md

@@ -101,8 +101,8 @@ interface CronChannelDispatcher {
   - no `supportsMedia` (telegram, feishu, wecom) → the **original text with `MEDIA:` lines intact** — the attachment degrades to a visible path instead of silently vanishing.
   - `CronMedia.workspacePath` is the **job's** workspace (where the run produced its files), not the target account's — it's the sandbox root for `isMediaPathAllowed` (paths outside workspace/OS-tmp are rejected with a failed result row). Cron passes no access level, so the `full`-account relaxation the chat handlers get does not apply here — the job workspace + OS tmp rule stays.
   - Wiring telegram/feishu up for real requires refactoring first, not copying: telegram's file send is an inline `sendPhoto/…/sendDocument` switch in `handler.ts`'s responder; feishu's `sendFeishuMedia` is anchored to an inbound `messageId` a cron run doesn't have. Extract the send-to-chat half in the channel module, then flip `supportsMedia: true` (details in each `cron-dispatcher.ts` header).
-- **Per-channel size limits are the dispatcher's job**, not the runner's: wechat splits the text at `WECHAT_TEXT_LIMIT` (3500 chars, shared `splitText` from `channels/shared/chunk.ts`) and sends the chunks in order — the ilink gateway rejects any single `sendmessage` over 16 KB with `ret=-2`. A failure on chunk *i* of *n* is recorded as `chunk i/n: <error>` in the target's `DispatchResult`, so the admin run row shows how much of the report already landed (a `failed` row no longer means "nothing arrived"). Telegram still sends one shot (Bot API caps at 4096) — same class of gap, unfixed.
-- **`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/WeCom require an explicit `chatId`). WeCom is the one dispatcher with **no HTTP send path**: it borrows the handler's live long-connect `WSClient` (`liveClients`), so a stopped / kicked / auth-exhausted account fails the target loudly (`wecom long-connect not active`) instead of queueing.
+- **Per-channel size limits are the dispatcher's job**, not the runner's: wechat splits the text at `WECHAT_TEXT_LIMIT` (3500 chars, shared `splitText` from `channels/shared/chunk.ts`) and sends the chunks in order — the ilink gateway rejects any single `sendmessage` over 16 KB with `ret=-2`. A failure on chunk *i* of *n* is recorded as `chunk i/n: <error>` in the target's `DispatchResult`, so the admin run row shows how much of the report already landed (a `failed` row no longer means "nothing arrived"). Telegram does the same at `TELEGRAM_TEXT_LIMIT` (4000 chars, the responder's limit — the Bot API caps a message at 4096), with the same `chunk i/n: <error>` failure row. The slack / feishu / wecom dispatchers still send the whole report as one message — same class of gap, unfixed.
+- **`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 default-recipient logic decides: WeChat falls back to the QR-bind owner, then the last active chat; Telegram/Slack/Feishu/WeCom require an explicit `chatId` and throw without one. WeCom is the one dispatcher with **no HTTP send path**: it borrows the handler's live long-connect `WSClient` (`liveClients`), so a stopped / kicked / auth-exhausted account fails the target loudly (`wecom long-connect not active`) instead of queueing.
 - `listTargets()` aggregates across all dispatchers (`listAllCronTargets`) to feed the admin create-form dropdown without the routes knowing any channel.
 
 ## Retention

package/bundled-docs/design/evolution.md

@@ -37,7 +37,7 @@ Let agents draft and validate improvements to their own prompt surface by learni
               next user message uses patched rules
 ```
 
-All coordination via global db (`~/.halo/global/evo.db`). Wrapper heartbeats every 60s; ticker marks `running` → `timeout` if stale. Detached process model: server restart doesn't kill in-flight wrappers.
+All coordination via global db (`~/.halo/global/evo.db`). Wrapper heartbeats every 60s; ticker requeues a stale `running` row (→ `timeout` once `max_attempts` is spent). Detached process model: server restart doesn't kill in-flight wrappers.
 
 ## Trigger and Enqueue Flow
 
@@ -52,12 +52,12 @@ User in chat:
 Server flow (synchronous, ~10ms):
 
 1. Refuse if user is not `full` access (not gated on `evolution.level`).
-2. Resolve root session id (must be `parentId === null`).
+2. Resolve the active session id; a sub-session id (contains `>`) is rejected.
 3. Call `enqueueEvoRun()` from `/packages/server/src/evolution/enqueue.ts`:
    - mkdir `<ws>/.halo/evo/runs/<id>/`
    - Write `source-snapshot.json` (frozen `session.agent.messages`)
    - Write `tool-flow.md` (tool_result-stripped Markdown view for skimming)
-   - Write `meta.json` (metadata: runId, triggerKind, sourceSession, userHint, createdAt)
+   - Write `meta.json` (metadata: id, triggerKind, sourceSession, userHint, workspacePath, createdAt)
    - Write `evo-context.json` (snapshot of prompt surface at trigger time: assembled system prompt, all prompt files, agent/skill listings)
 4. INSERT `evolution_runs` row with `status='pending'`, `trigger_kind='note'` (internal trigger id keeps the old name; only the user-visible command was renamed to `/evo`).
 5. Reply via `chat:system`: "📝 Queued for evaluation".
@@ -66,24 +66,22 @@ Server flow (synchronous, ~10ms):
 
 ### Pre-compact hook
 
-Inside `SessionManager.compactSession()`, **before** the compression LLM rewrites `session.agent.messages`:
+Compaction only sets a per-session `compactedThisTurn` flag; `SessionManager.enqueueEvoForCompactedTurn()` consumes it once the compact is done — at the end of `runSession` for auto-compact (mid-turn or turn-end), right after the summary lands for manual `/compact`. A turn that compacts several times therefore enqueues one run.
 
-1. Same checks (level=L1, root session, non-readonly user).
-2. Snapshot the current messages → `enqueueEvoRun()` with `trigger='pre-compact'`.
+1. Checks: `evolution.level` = L1, `evolution.triggers.pre_compact` on, root session (`parentId` null).
+2. `enqueueEvoRun()` with `trigger='pre-compact'` snapshots the session's current `rawMessages`. Because the enqueue is deferred, that is the already-compacted history (summary + kept tail), not the pre-compact one.
 3. INSERT `evolution_runs` row.
-4. Continue with normal compact.
-
-Order matters: snapshot first, compact second. Otherwise evo sees the already-compacted (summarized) message log, losing detail it should learn from.
 
 ## Ticker — Stateless Scheduler (every 30s)
 
 Located: `/packages/server/src/evolution/ticker.ts`
 
-Three jobs per pass:
+Four jobs per pass:
 
-1. **Mark timeouts**: `running` rows with heartbeat older than `runTimeoutMinutes` → `timeout`. Retry rows with `attempts < maxAttempts` back to `pending`; exhausted rows → terminal `timeout`.
+1. **Mark timeouts**: `running` rows (applies: also `syncing`) with heartbeat older than `runTimeoutMinutes` (`applyTimeoutMinutes` for applies) → back to `pending` while `attempts < maxAttempts`; exhausted rows → terminal `timeout` (a `syncing` apply → `failed`).
 2. **Start runs**: count current `running`, claim `pending` runs (oldest first, up to slot budget), spawn `evo-wrapper.js --mode=run --id=<X>`.
 3. **Start applies**: same shape, but with per-workspace mutex (only one apply per workspace at a time, since apply reads **current** main to build sandbox).
+4. **Broadcast**: diff in-flight run/apply statuses against the previous tick and push `evolution:run_changed` / `evolution:apply_changed` — wrappers are detached processes and can't reach the server's WS.
 
 Restart-safe: no in-memory state. On server reboot, ticker re-evaluates db on first tick — stale `running` rows timeout, pending rows continue to be picked up. Applies can resume mid-publish if they were in `syncing` state (heartbeat timeout was mid-phase-12).
 
@@ -95,7 +93,7 @@ The wrapper is the orchestrator; individual agents do focused work only. Every p
 
 ### Phase A — Draft
 
-`spawn('halo', ['cli', '-a', '__evo_agent__', '-n', '-w', '<runDir>/sandbox', '<draft-brief>'])`
+`spawn('halo', ['cli', '-a', '__evo_agent__', '-n', '-w', '<runDir>/sandbox'])` — the brief goes in on stdin (multi-KB; argv would hit Windows limits), capped at `PHASE_TIMEOUT_SEC` (30 min).
 
 Agent writes:
 - `patch.md` — Markdown with YAML frontmatter + body. Frontmatter includes `testScenario: { agentId, testMessage, originalMessage }` and `target: .halo/<path>`.
@@ -106,20 +104,20 @@ The `target` can be any file in the prompt surface — `INSTRUCTIONS.md`, the ag
 
 Sandbox is whitelist-cp from main workspace (only: `INSTRUCTIONS.md`, `INDEX.md`, `USER.md`, `agents/`, `prompts/`, `skills/`, `docs/`). Agent reads via `file_read`, writes only to `.halo/` subset.
 
-The copy is `copyDereferenced` (`evo-wrapper.ts:1419`), a hand-rolled recursive walk that resolves every symlink to its target's bytes, so the sandbox holds contents and never a link back into the live workspace (an evo edit through a link would write straight into main). It replaced `fs.cpSync({ dereference: true })` because Node ≥ 22.17 ignores `dereference` for symlinks nested below the top level (nodejs/node#59168; fix merged 2026-09-18, unreleased at the time).
+The copy is `copyDereferenced` in `evo-wrapper.ts`, a hand-rolled recursive walk that resolves every symlink to its target's bytes, so the sandbox holds contents and never a link back into the live workspace (an evo edit through a link would write straight into main). It replaced `fs.cpSync({ dereference: true })` because Node ≥ 22.17 ignores `dereference` for symlinks nested below the top level (nodejs/node#59168; fix merged 2026-09-18, unreleased at the time).
 
 ### Phase B — Dry-run + Fix Loop
 
 ```
-timeout 1800 halo cli -a <patch.testScenario.agentId> -n -w <runDir>/sandbox \
-  --access workspace <patch.testScenario.testMessage>
+halo cli -a <patch.testScenario.agentId> -n -w <runDir>/sandbox --access workspace
+  # testMessage on stdin; Node-side 1800s timer → exit 124
 ```
 
 `--access workspace` masks `~/.aws`, `~/.ssh`, etc. (safety: test probe's behavior, not side effects).
 
 Outcome:
 - **Success** (exit 0 + non-empty stdout): save to `dry-run-output.txt`, proceed to phase C.
-- **Failure**: save log, re-spawn `__evo_agent__` in fix mode with failure log inline. One corrective pass only (`FIX_BUDGET = 1`). If fix also fails, mark `failed` with reason "dry-run never succeeded".
+- **Failure**: save log, re-spawn `__evo_agent__` in fix mode with failure log inline. One corrective pass only (`FIX_BUDGET = 1`). If fix also fails, mark `failed` with reason "phase B: dry-run failed (fix budget exhausted)".
 
 Fix budget design:
 - Two-pass (original + one fix) covers common failure modes (bad YAML, scope-too-aggressive test scenario).
@@ -127,7 +125,7 @@ Fix budget design:
 
 ### Phase C — Score
 
-`spawn('halo', ['cli', '-a', '__score__', '-n', '-w', '<runDir>/sandbox', '<score-brief>'])`
+`spawn('halo', ['cli', '-a', '__score__', '-n', '-w', '<runDir>/sandbox'])` (brief on stdin)
 
 The score brief packs patch.md + dry-run-output.txt + meta.json + evo-context.json inline; the baseline conversation stays on disk (`tool-flow.md` / `source-snapshot.json`) and the brief directs the scorer to `file_read` it so behavior is graded against the actual baseline. Writes `score.json`:
 
@@ -160,7 +158,7 @@ After user approves N runs in the admin UI, `evolution_applies` row created with
 
 Wrapper builds **fresh sandbox** (whitelist-cp from **current main** workspace), then:
 
-`spawn('halo', ['cli', '-a', '__apply_agent__', '-n', '-w', '<applyDir>/sandbox', '<merge-brief>'])`
+`spawn('halo', ['cli', '-a', '__apply_agent__', '-n', '-w', '<applyDir>/sandbox'])` (brief on stdin)
 
 Agent reads each source run's `patch.md` (latest version!), merges changes into sandbox. Respects platform override matrix (workspace replaces global wholesale for agents/, skills/, prompts/). Agent writes `apply.log` (audit trail), edits only under `sandbox/.halo/`.
 
@@ -176,13 +174,13 @@ The wrapper clears any stale ABORT.md (from a crashed previous attempt) at the s
 For each source_run_id:
 
 1. Read `testScenario` from source run's `patch.md`.
-2. Run `timeout 1800 halo cli -a <agentId> -n -w <applyDir>/sandbox <testMessage>` against merged sandbox.
+2. Run `halo cli -a <agentId> -n -w <applyDir>/sandbox --access workspace` (testMessage on stdin, same 1800s timer) against merged sandbox.
 3. Spawn `__score__` with regress-mode brief, write `regress/<runId>/score.json`.
-4. Any score with `lint < 50` or `behavior < 50` → regression, abort with `failed`.
+4. Any score with `lint < 50` or `behavior < 50` (or a missing / malformed `score.json`) → regression, abort with `failed`.
 
 ### Phase 12 — Final Sync (checkpointed)
 
-Three substeps, two of them checkpointed:
+Four steps, with a checkpoint before the dangerous one:
 
 1. **Preflight** (idempotent): walk sandbox, diff against main, snapshot pre-apply files to `history/apply-<id>/` with `MANIFEST.json`.
 2. **Checkpoint**: set `evolution_applies.status='syncing'`. From here on, if wrapper crashes, ticker recovery resumes at step 3 (skip A'/B'/preflight to avoid re-running LLM phases).
@@ -216,6 +214,7 @@ Per-workspace mutex in ticker prevents two applies from racing on the same works
                               # diagnosis; first line becomes failureReason)
     regress/<runId>/          # one per source run
       dry-run-output.txt
+      dry-run-fail.log        # only when the regress dry-run failed
       score.json
   history/apply-<id>/         # rollback snapshot (NOT archived)
     MANIFEST.json             # which paths were overwritten
@@ -270,7 +269,7 @@ Active rows (pending/running/awaiting_review/approved/syncing) never archived. `
 
 Archive daemon runs at server boot (1 min delay) + daily. Idempotent.
 
-Zipping is **pure JS** (`jszip`, already a repo dependency via admin). It used to `spawnSync('zip', …)`, which depends on a system binary Windows installs don't have — so every archive pass failed there forever and artifacts grew unbounded. `zipDir()` walks the tree manually rather than using a recursive readdir, because the layout has to match what `zip -rq <out> .` produced and two cases need explicit handling: empty dirs get explicit folder entries, and **directory symlinks are not recursed** (an agent runs inside the sandbox during evaluation and could leave a cycle). File symlinks store the target's contents (what system `zip` without `-y` did); broken links are skipped instead of failing the pass. Contents are buffered per file (`createReadStream` for every entry would open all fds up front — EMFILE risk) and the zip is streamed to disk. On failure the partial zip is deleted, and `archiveRun`/`archiveApply` skip both the `rmDir` and the `archived_at` stamp, so the next pass retries from a clean state.
+Zipping is **pure JS** (`jszip`, a server dependency). It used to `spawnSync('zip', …)`, which depends on a system binary Windows installs don't have — so every archive pass failed there forever and artifacts grew unbounded. `zipDir()` walks the tree manually rather than using a recursive readdir, because the layout has to match what `zip -rq <out> .` produced and two cases need explicit handling: empty dirs get explicit folder entries, and **directory symlinks are not recursed** (an agent runs inside the sandbox during evaluation and could leave a cycle). File symlinks store the target's contents (what system `zip` without `-y` did); broken links are skipped instead of failing the pass. Contents are buffered per file (`createReadStream` for every entry would open all fds up front — EMFILE risk) and the zip is streamed to disk. On failure the partial zip is deleted, and `archiveRun`/`archiveApply` skip both the `rmDir` and the `archived_at` stamp, so the next pass retries from a clean state.
 
 ## Integration with SessionManager
 
@@ -280,13 +279,13 @@ After apply publishes to main, **no explicit session-release step needed**. Sess
 
 ## Key Files and Their Roles
 
-| File | Lines | Purpose |
-|---|---|---|
-| `/packages/server/src/evolution/enqueue.ts` | 403 | Snapshot session + prompt surface at trigger time. Write runDir/, INSERT evolution_runs. Both `/evo` and pre-compact hook call this. |
-| `/packages/server/src/evolution/ticker.ts` | 496 | Stateless 30s scheduler. Mark timeouts, claim pending, spawn wrappers. Per-workspace apply mutex. Broadcast status changes to admin UI. |
-| `/packages/server/src/evolution/spawn.ts` | 36 | Real spawner: detached Node child running evo-wrapper.js. Override-able for testing. |
-| `/packages/server/src/evolution/evo-wrapper.ts` | 2000+ | Wrapper orchestrator. 3-phase run mode (draft/dry-run/score). Apply mode (merge/regress/publish). Heartbeat every 60s. Handles Windows command-line limits via stdin briefs. |
-| `/packages/server/src/evolution/archive.ts` | 313 | Archive job: 14d → zip (pure-JS jszip) + delete, 30d → purge. Runs daily + at boot. Idempotent. |
+| File | Purpose |
+|---|---|
+| `/packages/server/src/evolution/enqueue.ts` | Snapshot session + prompt surface at trigger time. Write runDir/, INSERT evolution_runs. Both `/evo` and pre-compact hook call this. |
+| `/packages/server/src/evolution/ticker.ts` | Stateless 30s scheduler. Mark timeouts, claim pending, spawn wrappers. Per-workspace apply mutex. Broadcast status changes to admin UI. |
+| `/packages/server/src/evolution/spawn.ts` | Real spawner: detached Node child running evo-wrapper.js. Override-able for testing. |
+| `/packages/server/src/evolution/evo-wrapper.ts` | Wrapper orchestrator. 3-phase run mode (draft/dry-run/score). Apply mode (merge/regress/publish). Heartbeat every 60s. Handles Windows command-line limits via stdin briefs. |
+| `/packages/server/src/evolution/archive.ts` | Archive job: 14d → zip (pure-JS jszip) + delete, 30d → purge. Runs daily + at boot. Idempotent. |
 
 ## Sandbox Model
 
@@ -322,14 +321,14 @@ L0 = manual drafting only (`/evo`); L1 also enables pre-compact triggering. Defa
 
 Top-level "Evolution" tab shows:
 
-- **List**: evolution_runs + latest apply per run. Sortable by created_at / status / score.avg. Filterable by status. Joins runs+applies to show consolidated view.
-- **Detail**: patch.md, score.json, test scenario, assembled brief context, diff against current target.
-- **Approve**: Opens dialog, optional reviewer_hint. Flips the run to `approved` **and** inserts the pending `evolution_applies` row **inside one `db.transaction`** — it's a single reviewer decision, and half of it (run flipped, apply missing) strands the run in a status the ticker never advances.
+- **List**: evolution_runs + latest apply per run, newest first (cursor-paginated by `created_at`, up to 300 loaded). Filterable by status, plus an `archived` view. Joins runs+applies to show consolidated view.
+- **Detail**: patch.md (raw), score.json, the `.skip.md` reason, a snapshot summary (message count, first user / assistant message), wrapper log + sub-cli log.
+- **Approve**: Opens an inline panel, optional reviewer_hint. Flips the run to `approved` **and** inserts the pending `evolution_applies` row **inside one `db.transaction`** — it's a single reviewer decision, and half of it (run flipped, apply missing) strands the run in a status the ticker never advances.
 - **Reject**: Sets status='rejected'.
-- **Retry**: Resets row to pending, requires new hint. Allowed from any terminal status except `applied`.
-- **Manual Delete**: Removes artifacts (live dir + archive zip, whichever exists) + DB row immediately. Blocked on active rows (pending/running/approved/syncing).
+- **Retry**: Resets row to pending, requires new hint. The route allows any status except `pending` / `running`; the UI offers it on `awaiting_review`, `failed` / `timeout` / `skipped` / `rejected`, and on an `approved` run whose apply failed.
+- **Manual Delete**: Removes artifacts (live dir + archive zip, whichever exists) + DB row immediately. Blocked on `pending` / `running` / `approved` runs; also deletes the applies the run produced.
 
-Realtime updates via WebSocket (`evolution:run_changed`, `evolution:apply_changed` events). REST mutations broadcast directly; wrapper state changes broadcast at each ticker tick (15-30s latency).
+Realtime updates via WebSocket (`evolution:run_changed`, `evolution:apply_changed` events). REST mutations broadcast directly; wrapper state changes broadcast at each ticker tick (up to 30s latency).
 
 ## Crash Recovery and Restarts
 

package/bundled-docs/design/express-self.md

@@ -29,10 +29,12 @@ The marker is **stripped from rendered chat** so the user sees only the face mov
 
 **Runtime expression:** Agent emits `<<<SHOW: payload >>>` in a reply. On `chat:complete`:
 1. `chat-handlers.ts` takes the round's replies with `takeRoundReplies()` (`chat-store.ts`) — every main assistant bubble since the previous `chat:complete`, in log order, each handed out once. A round can span several bubbles (the head an interjection split off, a turnId split, the follow-up answering a queued message), so scanning only the last bubble would miss earlier markers
-2. `maybeHandleShow(replies)` detects all `<<<SHOW:[\s\S]*?>>>` markers (non-greedy, global) in those bubbles; `maybeHandleCapture(wsClient, replies)` looks for `<<<CAPTURE>>>` in the same set
+2. `maybeHandleShow(replies)` detects all `<<<SHOW:[\s\S]*?>>>` markers (non-greedy, global) in those bubbles; `maybeHandleCapture(wsClient, tabStore, replies)` looks for `<<<CAPTURE>>>` in the same set
 3. For each match, extracts the payload (trimmed)
 4. Calls `postToFace(payload)` to forward it
 
+`takeRoundReplies()` runs on every tab (it resets that tab's round), but steps 2–4 run only for the tab on screen — a background session must not drive the face the user is looking at.
+
 **No dedup set.** `takeRoundReplies()` advances a cursor (`roundStart`) past what it returned, so the duplicate `chat:complete`s a queue drain emits find no new bubbles and fire nothing. `setMessages` (history load, snapshot restore, reattach) and `clear()` reset the cursor to the end of the loaded log, so markers in already-loaded history never fire.
 
 **Forwarding:** `face-bridge.ts:postToFace()` posts to every registered iframe:
@@ -58,7 +60,7 @@ parsed.replace(/<<<CAPTURE>>>/g, '')
 
 ## The `self` API
 
-Provided by `self.html` from line 432 onwards (`const self = {…}`). All expression methods are sandboxed to the preview iframe.
+Provided by `self.html` as `const self = {…}`. All expression methods are sandboxed to the preview iframe.
 
 ### Scene queuing (sequential playback)
 
@@ -87,12 +89,12 @@ Provided by `self.html` from line 432 onwards (`const self = {…}`). All expres
 
 ## Key files
 
-- **Engine template:** `packages/server/templates/canvas/self.html` — particle field, mode switching, API surface, voice audio graph. ~630 lines. Canonical source; force-copied to every workspace on open.
+- **Engine template:** `packages/server/templates/canvas/self.html` — particle field, mode switching, API surface, voice audio graph. Canonical source; force-copied to every workspace on open.
 - **Skill instruction:** `packages/server/templates/skills/self/SKILL.md` — teaches the agent when/how to use the face.
 - **Marker detection:** `packages/admin/src/shared/ws-handlers/chat-handlers.ts:maybeHandleShow()` — regex match `<<<SHOW:([\s\S]*?)>>>` on the round's replies at `chat:complete`; the replies come from `takeRoundReplies()` in `chat-store.ts`, which hands each bubble out once.
 - **Iframe registration:** `packages/admin/src/features/editor/face-bridge.ts` — module-level registry of mounted previews; `postToFace()` forwards payloads via `postMessage`.
 - **Preview component:** `packages/admin/src/features/editor/html-preview.tsx` — sandboxed iframe with `allow-scripts` + `allow-same-origin` and `allow="autoplay"` (so `self.voice` audio, triggered by postMessage rather than a click, isn't gated), calls `registerFaceIframe()` on mount.
-- **Marker stripping:** `packages/admin/src/shared/components/message-list.tsx:TextBlock()` (line 630) — strips both `<<<CAPTURE>>>` and `<<<SHOW:...>>>` before rendering.
+- **Marker stripping:** `packages/admin/src/shared/components/message-list.tsx:TextBlock()` — strips both `<<<CAPTURE>>>` and `<<<SHOW:...>>>` before rendering.
 - **Workspace init:** `packages/server/src/init.ts:ensureWorkspaceHalo()` — force-copies engine on workspace open. `self` is in `BUILTIN_SKILL_IDS` so the skill is always available.
 
 ## Engine architecture

package/bundled-docs/design/feishu.md

@@ -14,7 +14,7 @@ Halo server (9527) ──┤├── channels/wechat/              ├── Se
                            https://open.feishu.cn
 ```
 
-Feishu uses the official SDK's `Lark.WSClient` to maintain a persistent WebSocket connection for event delivery. Unlike Slack/Telegram (which use webhooks + polling respectively), Feishu's long-connect receives `im.message.receive_v1` events pushed by the server over wss.
+Feishu uses the official SDK's `Lark.WSClient` to maintain a persistent WebSocket connection for event delivery. Unlike Telegram (long-polling), Feishu's long-connect receives `im.message.receive_v1` events pushed by the server over wss.
 
 ## Data model
 
@@ -70,7 +70,7 @@ Files: `packages/server/src/channels/feishu/`
 - `accounts.ts` — DAL (listAccounts / getAccount / insertAccount / updateAccount / deleteAccount / findAccountByAppId)
 - `handler.ts` — Lark.WSClient setup, event dispatch, message handling, mention detection, media ingestion; session routing + listener/route bookkeeping come from `channels/shared/inbound.ts` (`InboundBridge` / `deliverInbound` / `dispatchChannelCommand`)
 - `event-adapter.ts` — AgentSessionEvent stream → coalesced Feishu message replies (buffer + flush at paragraph boundaries)
-- `api.ts` — HTTP client (tenant token caching / getBotInfo / sendMessage / replyMessage / uploadImage / uploadFile / downloadResource / decryptWebhookBody / searchFeishuTargets / openLongConnection)
+- `api.ts` — HTTP client (tenant token caching / getBotInfo / sendMessage / replyMessage / uploadImage / uploadFile / downloadResource / decryptWebhookBody / searchFeishuTargets / openLongConnection); authenticated calls go through `fetchWithTenantToken` (401 → drop the cached token, retry once) and replies are parsed by `readFeishuJson`
 - `cron-dispatcher.ts` — registers the cron dispatcher, requires explicit chatId targets
 - `descriptor.ts` — ServerChannelDescriptor entry point
 
@@ -122,7 +122,7 @@ The SDK wraps protobuf marshalling; we just register an `EventDispatcher` callba
 
 ## Slash commands (native Feishu /commands)
 
-Implemented via `channels/shared/commands.ts` (shared across Telegram, WeChat, Slack, Feishu):
+Implemented via `channels/shared/commands.ts` (shared across Telegram, WeChat, Slack, Feishu, WeCom):
 
 | Command | Purpose |
 |---|---|
@@ -152,7 +152,9 @@ splitting produces several chunks in one synchronous loop and each is its own
 send API call, so firing them concurrently gave arrival order no guarantee. Each
 responder appends every chunk to a `sendTail` promise chain — chunk *n+1* waits
 for *n* to settle — and a rejected link is absorbed so one failed send doesn't
-stall the remainder (`dispatchChunk` logs it).
+stall the remainder (`dispatchChunk` logs it). Both live in the shared
+`ChunkedResponder` (`channels/shared/responder.ts`); `FeishuResponder` only
+supplies the 4500 limit and `formatForFeishu`.
 
 `close()` returns that drain promise and `InboundBridge` holds the session's
 reply route until it settles, then deletes it; the `stopAccount` / `closeAll()`
@@ -170,7 +172,7 @@ trailing chunks of a long reply were dropped.
 - `.mp4/.mov/.webm/.m4v/.avi` → `uploadFile(fileType: 'mp4')` → `msg_type: 'media'` (with optional cover frame)
 - everything else → `uploadFile(fileType: 'stream')` → `msg_type: 'file'`
 
-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 throws inside the same try as the upload, so it surfaces as the `t('handler.upload_failed')` reply rather than a silent drop.
+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 throws inside the same try as the upload (`sendMediaOrReport` in `channels/shared/media.ts`), so it surfaces as the `t('handler.upload_failed')` reply rather than a silent drop.
 
 Inbound images are downloaded via `/im/v1/messages/{messageId}/resources/{imageKey}?type=image`, decrypted if needed, saved under `<workspace>/.halo/assets/feishu/inbound/<accountId>/<date>/`, and fed to vision.
 
@@ -180,17 +182,19 @@ Inbound images are downloaded via `/im/v1/messages/{messageId}/resources/{imageK
 
 **Group (chat):** Replies sent via `replyMessage` with `reply_in_thread: true` and the inbound message id. This auto-creates a thread rooted at the inbound message if it doesn't exist, or appends to the existing thread.
 
+**After a restart**, `startAccount` calls `restoreReplyRoute()` to re-wire the reply route from `lastActiveChatId` (`restoreChannelRoute` in `channels/shared/inbound.ts`, no session created). p2p only: a group-thread reply needs the inbound message id, which isn't persisted, so group threads re-wire on their next inbound message.
+
 ## Similarities vs Slack and Telegram
 
 | Aspect | Feishu | Slack | Telegram |
 |--------|--------|-------|----------|
-| **Inbound delivery** | Long-connect (wss) | Webhook + slash commands | Long-polling |
+| **Inbound delivery** | Long-connect (wss) | Socket Mode (wss) | Long-polling |
 | **Session model** | Per-thread in groups, p2p anchored | Per-thread + channels | Per-user (one active) |
 | **Mention required** | Yes in groups, no in p2p | Yes in channels, no in DMs | No (all messages routed to agent) |
 | **Cron target** | Explicit chatId only | Explicit chatId only (DM / channel / thread) | Explicit numeric chatId only |
 | **Media upload** | Separate image + file endpoints | Unified File upload API | Bot API sendPhoto / sendVideo / sendDocument |
-| **Text limit** | ~5000 chars | ~4000 chars | ~4000 chars |
-| **Thread support** | Native (root_id in messages) | Native (thread_ts replies) | N/A (group chats not supported) |
+| **Text limit** | 4500 chars per message | 35000 chars per message | 4000 chars per message |
+| **Thread support** | Native (root_id in messages) | Native (thread_ts replies) | N/A (group chats supported, no threads; sessions keyed by sender) |
 
 ## Configuration
 
@@ -230,10 +234,10 @@ Not supported: group chat without mention (we require explicit @mention for grou
 
 ## Key file references
 
-- Long-connect: `packages/server/src/channels/feishu/handler.ts:connect()` (line 241)
-- Token caching: `packages/server/src/channels/feishu/api.ts:getTenantAccessToken()` (line 39)
-- Message parsing: `packages/server/src/channels/feishu/handler.ts:parseContent()` (line 135)
-- Event dispatch: `packages/server/src/channels/feishu/handler.ts:handleInbound()` (line 301)
-- Cron dispatch: `packages/server/src/channels/feishu/cron-dispatcher.ts:dispatch()` (line 27)
-- Event coalescing: `packages/server/src/channels/feishu/event-adapter.ts:FeishuResponder` (line 24)
+- Long-connect: `packages/server/src/channels/feishu/handler.ts` `connect()`
+- Token caching: `packages/server/src/channels/feishu/api.ts` `getTenantAccessToken()`
+- Message parsing: `packages/server/src/channels/feishu/handler.ts` `parseContent()`
+- Event dispatch: `packages/server/src/channels/feishu/handler.ts` `handleInbound()`
+- Cron dispatch: `packages/server/src/channels/feishu/cron-dispatcher.ts` `dispatch()`
+- Event coalescing: `packages/server/src/channels/feishu/event-adapter.ts` `FeishuResponder`, extending `channels/shared/responder.ts` `ChunkedResponder`
 - REST routes: `packages/server/src/routes/feishu.ts` (all account CRUD + search)

package/bundled-docs/design/halo-city.md

@@ -65,7 +65,7 @@ Halo 服务器运行态的**街景式**像素可视化:侧视、剖面的像素
 | 🛸 UFO | 每天 0:00 | 午夜从街头飘过 |
 | ✈️ 飞机 | 每半点(`:30`) | 高空掠过,方向随机 |
 | 🚌 巴士 | 每 3 分钟 | 进站、开门、接走在站台等车的人,再开走 |
-| 🚗 进出场载具 | 跟随会话 | 新会话打车/电动车/跑车送到门口;结束的会话走到站台**体面地等车离场**,不再凭空消失 |
+| 🚗 进出场载具 | 跟随会话 | 新根会话坐出租车或小轿车送到门口(子代理直接淡入,不配车);结束的会话走到站台**体面地等车离场**,不再凭空消失 |
 | 🏗️ 盖楼 / 拆楼 | 跟随楼层增减 | 长楼层有施工动效;拆楼留 ~30s 缓冲(先让人撤离再慢慢消散,不穿帮) |
 
 > 定时全用真实 `Date.now()` 计算(`?hour=` 只冻结天色、不冻结这些事件)。
@@ -73,8 +73,8 @@ Halo 服务器运行态的**街景式**像素可视化:侧视、剖面的像素
 ## 交互与显示
 
 操作:滚轮缩放(九档 `0.3×–6×`)· 拖拽平移 · 点击查看 · **双击**在 1×/3× 间快速切 ·
-**F** 全街区 · **H**(或点左上角 logo)切纯净模式 · **Esc** 逐层退(先关面板,再退纯净)·
-右上角 **中/EN** 一键切语言。闲置 10s 后镜头沿街慢慢巡游。
+**F** 全街区 · **H**(或点左上角 logo)切纯净模式 · **Esc** 先关面板,没有面板时切纯净模式 ·
+右上角 **中/EN** 一键切语言。
 
 - **纯净模式(zen)**:淡出所有 HUD(统计/动态/图例/缩放条/面板),只留街景,适合大屏常驻展示
 - **多语言(i18n)**:中文 / English 一键切;`?lang=en`/`?lang=zh` 直达,选择存 localStorage。
@@ -104,6 +104,7 @@ js/
   camera.js    整数吸附镜头(九档缩放 0.3×–6×)
   inspector.js 面板 + 实时会话日志查看器
   ticker.js    街区动态 feed
+  music.js     背景音乐:纯 Web Audio 程序生成
   traffic.js   街景事件:UFO(0点)/飞机(每半点)/进出场载具/每 3 分钟 bus/盖楼·拆楼
   i18n.js      多语言词典(zh/en)+ 运行时 t() + 静态 data-i18n 填充
   util.js      hash/PRNG/格式化
@@ -117,7 +118,7 @@ js/
   token 铸造的会话**(id 以 `web_<accountId>_` 开头);点其它市民会 403,
   前端在 inspector 里显示加载失败框而不是 transcript
 - `/api/show/state` — 无活跃 UIState 的会话(idle/stopped/重启后)token
-  从会话文件头读取(mtime 缓存,不随轮询刷盘),不显示 0;含 `messageCount` 字段
+  从会话文件头读取(按会话 `updatedAt` 缓存,未变化时不随轮询重读),不显示 0;含 `messageCount` 字段
 
 > **`messageCount` 与 admin 的 `exchangeCount` 是两个语义,不要互相对齐**:
 > 这里读的是会话文件里的 `messageCount`(活跃 UI 日志的长度),城市只把它