diff --git a/Makefile b/Makefile
index 37aa835..7ab13b6 100644
--- a/Makefile
+++ b/Makefile
@@ -16,3 +16,7 @@ up:
 
 down:
 	@bash scripts/down.sh
+
+restart:
+	@bash scripts/down.sh
+	@bash scripts/up.sh
diff --git a/bun.lock b/bun.lock
index 47a60c3..ea384a5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -16,6 +16,7 @@
         "pino": "^10.3.1",
         "pino-pretty": "^13.1.3",
         "uuid": "^13.0.0",
+        "yaml": "^2.8.3",
       },
       "devDependencies": {
         "@eslint/js": "^10.0.0",
@@ -760,7 +761,7 @@
 
     "y18n": ["y18n@5.0.8", "https://registry.npmmirror.com/y18n/-/y18n-5.0.8.tgz", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
 
-    "yaml": ["yaml@2.8.2", "https://registry.npmmirror.com/yaml/-/yaml-2.8.2.tgz", { "bin": { "yaml": "bin.mjs" } }, "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A=="],
+    "yaml": ["yaml@2.8.3", "https://bnpm.byted.org/yaml/-/yaml-2.8.3.tgz", { "bin": { "yaml": "bin.mjs" } }, "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg=="],
 
     "yargs": ["yargs@17.7.2", "https://registry.npmmirror.com/yargs/-/yargs-17.7.2.tgz", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w=="],
 
@@ -796,6 +797,8 @@
 
     "fdir/picomatch": ["picomatch@4.0.3", "https://registry.npmmirror.com/picomatch/-/picomatch-4.0.3.tgz", {}, "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q=="],
 
+    "lint-staged/yaml": ["yaml@2.8.2", "https://registry.npmmirror.com/yaml/-/yaml-2.8.2.tgz", { "bin": { "yaml": "bin.mjs" } }, "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A=="],
+
     "log-update/slice-ansi": ["slice-ansi@7.1.2", "https://registry.npmmirror.com/slice-ansi/-/slice-ansi-7.1.2.tgz", { "dependencies": { "ansi-styles": "^6.2.1", "is-fullwidth-code-point": "^5.0.0" } }, "sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w=="],
 
     "send/mime-types": ["mime-types@3.0.2", "https://registry.npmmirror.com/mime-types/-/mime-types-3.0.2.tgz", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
diff --git a/docs/designs/group-workspace-binding.md b/docs/designs/group-workspace-binding.md
new file mode 100644
index 0000000..b163f27
--- /dev/null
+++ b/docs/designs/group-workspace-binding.md
@@ -0,0 +1,210 @@
+# Group Workspace Binding Design
+
+Enable one agentara bot to serve multiple Feishu groups. Each group binds to its own workspace (a multi-repo directory) with an active `(repo, branch)` pointer. Every Feishu topic inside a group becomes an isolated session that follows the group's live binding.
+
+## Goals
+
+- One bot process, N Feishu groups — registered dynamically at runtime
+- Per-group workspace directory (can host multiple cloned repos, all visible to the agent in one session)
+- Per-topic session within a group (flexible + isolated)
+- Gateway-level slash commands that bypass the LLM
+- Default workspace fallback when a group is not bound
+- `dev-assets` memory works across all repos in the workspace (requires the suite-side workspace mode — see `branch-context-skill-suite/docs/workspace-mode.md`)
+
+## Non-Goals
+
+- Per-topic workspace override (binding lives at group level only)
+- Multiple simultaneously-active repos inside one workspace
+- Rich card UI for `/setup` in v1 (text commands first, card in v2)
+
+## Data Model
+
+### `group_workspaces` (new table)
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `chat_id` | text, PK | Feishu `chat_id` |
+| `workspace_path` | text | Absolute path, always `$AGENTARA_HOME/workspaces/<chat_id>/` |
+| `active_repo` | text, nullable | Directory name under `workspace_path` |
+| `active_branch` | text, nullable | Git branch name |
+| `created_at` | int | epoch ms |
+| `updated_at` | int | epoch ms |
+
+Row absence = group is unbound. `active_repo = null` while `workspace_path` exists = workspace reserved but no repo selected yet.
+
+### `sessions` (schema extension)
+
+Add two fields to the existing `Session` schema (`src/shared/sessioning/types/session.ts`):
+
+- `chat_id: string | null` — owning Feishu group
+- `thread_id: string | null` — Feishu topic root message id
+
+Keep `cwd` for backward compatibility, but **it is now a hint, not a source of truth**. Actual cwd is resolved dynamically on every dispatch (see Resolution Flow).
+
+### Default workspace
+
+Path: `$AGENTARA_HOME/workspaces/_default/`
+
+Created by boot-loader on first run. Used when a message arrives from an unbound group or from a group whose binding has `active_repo = null`.
+
+## Feishu Channel Rework
+
+### Current (`src/kernel/kernel.ts:87-99`)
+
+`config.yaml` lists each Feishu channel; one `FeishuMessageChannel` instance per chat, constructor-bound to a specific `chat_id`. Adding a group = editing config + restart.
+
+### New
+
+- Exactly one `FeishuMessageChannel` instance, **no `chat_id` filter**
+- Subscribes to all group events the bot is a member of (Feishu WS IM event stream already broadcasts to the bot user; filter only on event type, not chat)
+- Inbound event carries `chat_id` + `root_id` (topic id when the message is inside a topic; equals message id otherwise)
+- `UserMessage.channel_id` remains the agentara internal channel id (single value for the one Feishu channel); the Feishu `chat_id` and `root_id` are carried as new fields on `UserMessage`
+
+### Session id derivation
+
+```
+session_id = `feishu:${chat_id}:${thread_id}`
+```
+
+- First message inside a topic → `resolveSession` creates
+- Subsequent messages in same topic → `resolveSession` resumes
+- Messages outside any topic (direct `@mention` with no threading) → treated as topic whose `thread_id = message_id` (each becomes its own fresh session; encourages the bot to always reply in a topic so follow-ups resume correctly)
+
+## Gateway Commands
+
+Parsed in `Kernel._handleInboundMessage` (`src/kernel/kernel.ts:114`) before `TaskDispatcher.dispatch()`. Prefix: `/` (matches Claude Code convention). Commands execute synchronously, reply via `_messageGateway.replyMessage`, do not dispatch an LLM task.
+
+| Command | Scope | Effect |
+|---------|-------|--------|
+| `/setup` | group | Reply with an interactive card. User picks repo + branch; card submit writes group binding. v1 may fall back to `/bind`. |
+| `/bind <repo> <branch>` | group | Upsert `group_workspaces` row, set `active_repo` + `active_branch`. Rejects if `<repo>` not in workspace (suggests `/clone`). |
+| `/unbind` | group | Delete `group_workspaces` row. |
+| `/status` | group + topic | Show group binding, list cloned repos, show current topic's `session_id`. |
+| `/clone <git-url> [name]` | group | `git clone` into `workspace_path`. Rejects on name collision. |
+| `/checkout <branch>` | group | `git checkout` in active repo; updates `active_branch`. Rejects on dirty tree. |
+| `/ls` | group | List directories under `workspace_path`. |
+| `/new` | topic | Archive current session for this topic; next message opens a new session with the same `session_id` reset (or appends a generation suffix). |
+| `/agent <claude\|codex>` | topic | Overrides `agent_type` for the current session only; re-resolve session with new runner type. |
+
+Already-implemented reference: `/stop` (`src/kernel/kernel.ts:118`). Extend the same if-chain into a command table.
+
+Card interaction for `/setup` should mirror the streaming card pattern in `remote_claude/lark_client/shared_memory_poller.py` + interactive element handling in Feishu card-action callbacks. Deferred to v2.
+
+## Resolution Flow
+
+Per inbound Feishu message:
+
+1. `FeishuMessageChannel` emits `message:inbound` with `{ chat_id, thread_id, text, ... }`
+2. `Kernel._handleInboundMessage`:
+   - If text starts with `/` → dispatch to gateway command handler, reply, return
+   - Else compute `session_id` from `(chat_id, thread_id)`
+   - `TaskDispatcher.dispatch(session_id, { type: "inbound_message", message })`
+3. `Kernel._handleInboundMessageTask`:
+   - Load `group_workspaces` row for `chat_id`
+   - Resolve cwd:
+     - No row → `cwd = $AGENTARA_HOME/workspaces/_default/`
+     - Otherwise → `cwd = workspace_path` (the workspace root, multi-repo container — **not** a single repo dir)
+   - If `active_repo` set: pre-checkout `git -C <workspace_path>/<active_repo> checkout <active_branch>` (idempotent)
+   - Build runner env extras:
+     - If `active_repo` set: `DEV_ASSETS_PRIMARY_REPO=<active_repo>`, `DEV_ASSETS_PRIMARY_BRANCH=<active_branch>`
+     - Else: omit (skill suite enters workspace mode without primary hint)
+   - `SessionManager.resolveSession(session_id, { cwd, chatId, threadId, envExtras, firstMessage })`
+   - `session.stream(message)` as today
+
+The cwd passed to `resolveSession` on resume overrides the stored `cwd` (supported today at `src/kernel/sessioning/session-manager.ts:174`). This is the mechanism for "live binding": each dispatch re-resolves. `envExtras` is a new option threaded through to the runner's `Bun.spawn` call so per-group env vars reach the underlying CLI.
+
+## dev-assets Integration
+
+The cwd contract changed: cwd is the group's workspace root (`workspaces/<chat_id>/`), which is **not** a git repo but contains N cloned repos as first-level subdirectories. The native `dev-assets` skills assume cwd is inside a single git repo, so the suite needs an additive **workspace mode**. Suite-side design lives in `branch-context-skill-suite/docs/workspace-mode.md`. Summary:
+
+- `lib/dev_asset_common.py` gains `detect_workspace_mode()` + `list_repos_in_workspace()` (purely additive)
+- Hook scripts (`session_start.py`, `stop.py`, `pre_compact.py`, `session_end.py`) take a workspace branch: when cwd has no `.git` but first-level subdirs do, iterate all repos
+- Single-repo cwd behavior is unchanged; existing installations see no difference
+
+### agentara-side contract
+
+When dispatching, agentara passes to the runner:
+
+- `cwd = workspaces/<chat_id>/` (workspace root)
+- env `DEV_ASSETS_PRIMARY_REPO=<active_repo>` (basename) — focus repo from group binding
+- env `DEV_ASSETS_PRIMARY_BRANCH=<active_branch>` — informational
+
+The skill suite then:
+
+- **SessionStart**: full memory for primary repo + brief overview-only summary for other repos in workspace
+- **Stop / SessionEnd**: record HEAD for all repos in workspace (cheap, idempotent)
+- **dev-assets-sync** (LLM-invoked): defaults to primary when no `--repo` flag; LLM can pass `--repo=<name>` to write to another repo
+- **dev-assets-context** (LLM-invoked): can target a non-primary repo via `--repo=<name>` to load its full memory mid-session
+
+Codex parity: SessionStart + Stop hooks fire identically. Codex lacks PreCompact/SessionEnd, but those don't affect multi-repo correctness — only Claude-only checkpoint refinement.
+
+### Default workspace
+
+For `_default` (no binding): no `DEV_ASSETS_PRIMARY_REPO` set. Suite enters workspace mode and lists whatever repos the user happens to have cloned in there. Empty `_default` → suite no-ops (acceptable).
+
+### Cross-group memory sharing
+
+Memory is keyed by `(repo_identity, branch)` derived from git remote URL (or local path fallback). Two groups bound to the same `(repo, branch)` automatically share memory under `~/.dev-assets/repos/<repo-key>/branches/<branch-key>/` — no agentara code involved.
+
+## Concurrency & Ordering
+
+- Same `(chat_id, thread_id)` → same `session_id` → serial execution via `TaskDispatcher`'s per-session queue (existing guarantee).
+- Different topics in same group → different `session_id` → parallel execution (existing guarantee).
+- `/checkout` interleaved with an in-flight LLM turn in another topic of the same group: the running runner's `cwd` (workspace root) is unchanged, but the active repo's HEAD shifts under it. Tool calls touching `<workspace>/<active_repo>/**` may see the new branch's files mid-turn. Acceptable per Q6(b) — live binding is the user's explicit choice. Other repos in the workspace are unaffected.
+- Two simultaneous `/checkout` on same group: serialize via a per-chat mutex in the gateway command layer (reuse `TaskDispatcher` isn't right — commands are synchronous). Simple `Map<chat_id, Promise>` mutex.
+
+## Error Handling
+
+Strict; no silent coercion.
+
+- `/bind <repo> <branch>` where `<repo>` directory absent → reply with suggestion to run `/clone`.
+- `/clone` with name collision → reject.
+- `/checkout` on dirty tree → reply with `git status --short` output; require user to resolve manually.
+- `/unbind` when no row → reply "group is not bound".
+- Inbound message from group with no binding → silently fall back to `_default`, no error.
+- Feishu event missing `chat_id` → log error, drop event.
+- Gateway command execution failure → reply with error text; do not dispatch LLM fallback.
+
+## Config Changes
+
+`config.yaml`:
+
+- `messaging.channels` entries for Feishu no longer need `chat_id` (ignored if present, logged as deprecation)
+- Add optional `messaging.default_workspace_path` to override `$AGENTARA_HOME/workspaces/_default/`
+
+No breaking change for users with existing single-chat config — a missing `chat_id` is now valid and means "listen to all groups".
+
+## Files Touched
+
+| File | Change |
+|------|--------|
+| `src/shared/sessioning/types/session.ts` | Add `chat_id`, `thread_id` fields |
+| `src/kernel/sessioning/data.ts` | Drizzle schema: add columns + new `group_workspaces` table |
+| `src/kernel/sessioning/session-manager.ts` | Pass through new fields on create/resume |
+| `src/kernel/workspaces/` (new dir) | `GroupWorkspaceStore` (CRUD over `group_workspaces`), cwd resolver |
+| `src/kernel/commands/` (new dir) | Slash command parser + handlers |
+| `src/community/feishu/messaging/` | Remove per-chat filter; forward `chat_id` + `root_id` on inbound |
+| `src/kernel/kernel.ts` | Wire command parser into `_handleInboundMessage`; wire cwd resolver + env extras into `_handleInboundMessageTask` |
+| `src/shared/agents/agent-runner.ts` | Add `envExtras?: Record<string, string>` to `AgentRunOptions` schema |
+| `src/community/anthropic/claude-agent-runner.ts` | Merge `envExtras` into `Bun.spawn` env (preserve `ANTHROPIC_API_KEY: ""` clear for subscription auth) |
+| `src/community/openai/codex-agent-runner.ts` | Merge `envExtras` into `Bun.spawn` env |
+| `src/shared/messaging/types/message.ts` | Extend `UserMessage` with `chat_id`, `thread_id` optional fields |
+| `src/boot-loader/boot-loader.ts` | Ensure `workspaces/_default/` exists on first run |
+| `docs/overview.md` | Append "Group Workspace Binding" section linking here |
+
+## Implementation Order
+
+1. Schema additions (`group_workspaces` table, `Session` fields, `UserMessage` fields) + migration
+2. `GroupWorkspaceStore` CRUD + cwd resolver
+3. Feishu channel multi-group refactor (forward `chat_id` + `root_id`)
+4. Session id derivation in kernel from `(chat_id, thread_id)`
+5. Dynamic cwd resolution at dispatch
+6. Slash command parser + core handlers (`/bind`, `/unbind`, `/status`, `/clone`, `/checkout`, `/ls`)
+7. `/new`, `/agent` — session lifecycle commands
+8. Default workspace bootstrap
+9. v2: `/setup` Feishu card interaction
+
+## Open Questions
+
+- Feishu `root_id` behavior when the bot itself opens a topic vs when user does: verify the id is stable across the whole thread. (Implementation detail; does not change design.)
+- `/new` semantics: does archiving mean deleting the JSONL or renaming? Propose rename to `<session_id>.archived-<ts>.jsonl` so the DB row is kept for audit. Decide during implementation.
diff --git a/docs/designs/setup-flow.md b/docs/designs/setup-flow.md
new file mode 100644
index 0000000..9b79023
--- /dev/null
+++ b/docs/designs/setup-flow.md
@@ -0,0 +1,127 @@
+# SetupFlow Design
+
+Interactive `/setup` command: presents a Feishu card with pre-defined repositories (sourced from `$AGENTARA_HOME/REPOS.md`), collects user's repo+branch selections via a form submit, then clones, checks out, and binds the group workspace in one shot.
+
+Specialized, **not** generic — no broader "interactive card framework". Only `/setup` triggers this path. Day-to-day binding uses `/bind <repo> <branch>`.
+
+## Dependencies
+
+- `src/shared/config/predefined-repos.ts` — `PredefinedRepo` Zod schema + `loadPredefinedRepos()` Markdown parser
+- `src/community/feishu/messaging/types/interactive/` — element types (form, checker, input, button, column_set, select_static)
+- `src/community/feishu/messaging/message-channel.ts` — subscribes `card.action.trigger`, emits `card:action`, exposes `sendRawCard` and `updateRawCard`
+- `src/shared/messaging/message-channel.ts` + `message-gateway.ts` — `"card:action"` event type
+- `src/kernel/workspaces/store.ts` — reuses `upsertBinding`, `resolve`
+- `src/kernel/kernel.ts` — special-cases `/setup` like `/stop`; subscribes `card:action`
+- `src/boot-loader/boot-loader.ts` — seeds an empty `REPOS.md` on first boot and ensures CLAUDE.md references it
+
+## Source — `$AGENTARA_HOME/REPOS.md`
+
+The repo catalog lives in a Markdown file instead of `config.yaml` so the
+same file can double as agent-readable context. CLAUDE.md imports it via
+Claude Code's native `@REPOS.md` syntax; the boot-loader appends that
+reference automatically if missing.
+
+Each `## <name>` section defines one repo. The first `- git_url: <url>`
+bullet supplies the clone URL; the first non-bullet prose line becomes
+the one-line description rendered on the card. The rest of the section
+body is free-form prose for the agent — and the agent is expected to
+update those descriptions over time as it learns more about each repo.
+
+```markdown
+## agentara
+
+- git_url: https://github.com/magiccube/agentara.git
+
+Bun + TypeScript personal assistant. Useful when a group is discussing
+the kernel, session/task orchestration, or Feishu bot integration.
+```
+
+When `REPOS.md` is missing or yields zero parseable entries, `/setup`
+replies with an error pointing the operator at the file.
+
+`loadPredefinedRepos()` is called on every `/setup` invocation — no
+caching — so edits to the Markdown take effect immediately.
+
+## Card Shape
+
+Single Feishu Card 2.0 form with one row per predefined repo. Each row is a `column_set` with:
+- `checker` — `name: repo_<name>`, label is `<name>` (plus `— <description>` when present)
+- `input` — `name: branch_<name>`, `placeholder: master`, no default value (empty submission means master)
+
+Below the rows: a `select_static` for primary-repo selection (`name: primary_repo`, options built from the catalog), always shown.
+
+Footer: `button` with `name: "setup_submit"` and `action_type: form_submit`.
+
+## Events
+
+`FeishuMessageChannel` handles `card.action.trigger` and normalizes the SDK payload into a minimal shape:
+
+```ts
+interface CardActionPayload {
+  message_id: string;
+  action_name: string;                // button/element name (e.g. "setup_submit")
+  operator_open_id: string;           // who clicked
+  form_value: Record<string, unknown>;// input/checker values on form_submit
+  chat_id: string;
+}
+```
+
+Emitted as `card:action` on the channel; `MultiChannelMessageGateway` re-emits; kernel dispatches by `action_name` (only `"setup_submit"` recognized).
+
+## API
+
+### `SetupFlow` (`src/kernel/setup/setup-flow.ts`)
+
+```ts
+class SetupFlow {
+  constructor(deps: {
+    workspaceStore: GroupWorkspaceStore;
+    feishuChannels: Map<string, FeishuMessageChannel>; // by channel_id
+  });
+
+  // Entry: called from kernel._handleInboundMessage when text === "/setup"
+  start(message: UserMessage): Promise<void>;
+
+  // Entry: called from kernel card:action listener when action_name === "setup_submit"
+  handleSubmit(payload: CardActionPayload): Promise<void>;
+}
+```
+
+### Pending state
+
+In-memory `Map<messageId, PendingSetup>` on the `SetupFlow` instance:
+
+```ts
+interface PendingSetup {
+  chat_id: string;
+  initiator_open_id: string;
+  catalog_snapshot: PredefinedRepo[]; // frozen at card render time
+  created_at: number;
+}
+```
+
+Lost on kernel restart — acceptable. On submit for an unknown `message_id`, the card is updated in place with an "expired, please re-run /setup" message.
+
+## Error Handling
+
+- `/setup` when `REPOS.md` is missing or empty → text reply: ask operator to fill in `REPOS.md`.
+- `/setup` when the group is already bound (`upsertBinding` already present) → text reply: `已绑定 <repo>@<branch>，请先 /unbind`.
+- `/setup` outside Feishu (`!message.chat_id`) → text reply: `/setup 仅在飞书群内可用`.
+- Submit by non-initiator → update card: `这不是你的表单`.
+- No repos selected on submit → update card: `未选择任何仓库`.
+- Per-repo clone failure → keep successful clones, record the failed entry; show per-repo status in result card.
+- Per-repo checkout failure → keep the clone, bind to whatever the clone landed on; warn on the card.
+- All throws from the submit path → update card with `❌ 初始化失败: <err>`.
+
+No silent fallback. No graceful retry. Every failure surfaces on the card.
+
+## Concurrency / Constraints
+
+- Single-writer to pending state: all access through one `SetupFlow` instance on the kernel.
+- One pending setup per `chat_id` — a second `/setup` while another is pending replaces the first card's pending entry (in-memory map is keyed by `message_id`, so the earlier card becomes unreachable and effectively expired).
+- Clone operations run sequentially within one submit, keeping output deterministic and avoiding concurrent writes to the same workspace directory.
+- Primary-repo select always offers the full catalog (not just checked rows). If the primary isn't among the checked rows on submit, the handler falls back to the first checked row instead of rejecting.
+
+## Result Card
+
+After submit completes (success or partial), the original card is replaced with a result card (via `updateRawCard`) showing per-repo status (`✅ cloned` / `⚠️ checkout failed` / `❌ clone failed`), the final binding, and next-step hints.
diff --git a/drizzle/0011_lean_enchantress.sql b/drizzle/0011_lean_enchantress.sql
new file mode 100644
index 0000000..a422cf1
--- /dev/null
+++ b/drizzle/0011_lean_enchantress.sql
@@ -0,0 +1,11 @@
+CREATE TABLE `group_workspaces` (
+	`chat_id` text PRIMARY KEY NOT NULL,
+	`workspace_path` text NOT NULL,
+	`active_repo` text,
+	`active_branch` text,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE `sessions` ADD `chat_id` text;--> statement-breakpoint
+ALTER TABLE `sessions` ADD `thread_id` text;
\ No newline at end of file
diff --git a/drizzle/0012_workspace_ids.sql b/drizzle/0012_workspace_ids.sql
new file mode 100644
index 0000000..2272e93
--- /dev/null
+++ b/drizzle/0012_workspace_ids.sql
@@ -0,0 +1,65 @@
+CREATE TABLE `workspaces` (
+	`id` text PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`path` text NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `workspaces_path_unique` ON `workspaces` (`path`);
+--> statement-breakpoint
+WITH RECURSIVE `workspace_name_parts`(`chat_id`, `path`, `tail`) AS (
+	SELECT
+		`chat_id`,
+		rtrim(`workspace_path`, '/'),
+		rtrim(`workspace_path`, '/')
+	FROM `group_workspaces`
+	UNION ALL
+	SELECT
+		`chat_id`,
+		`path`,
+		substr(`tail`, instr(`tail`, '/') + 1)
+	FROM `workspace_name_parts`
+	WHERE instr(`tail`, '/') > 0
+)
+INSERT OR IGNORE INTO `workspaces` (`id`, `name`, `path`, `created_at`, `updated_at`)
+SELECT
+	'ws_' || lower(hex(randomblob(6))),
+	COALESCE(NULLIF(`parts`.`tail`, ''), '_workspace'),
+	`parts`.`path`,
+	`gw`.`created_at`,
+	`gw`.`updated_at`
+FROM `workspace_name_parts` AS `parts`
+JOIN `group_workspaces` AS `gw` ON `gw`.`chat_id` = `parts`.`chat_id`
+WHERE instr(`parts`.`tail`, '/') = 0;
+--> statement-breakpoint
+ALTER TABLE `group_workspaces` RENAME TO `group_workspaces__old`;
+--> statement-breakpoint
+CREATE TABLE `group_workspaces` (
+	`chat_id` text PRIMARY KEY NOT NULL,
+	`workspace_id` text NOT NULL,
+	`active_repo` text,
+	`active_branch` text,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+INSERT INTO `group_workspaces` (
+	`chat_id`,
+	`workspace_id`,
+	`active_repo`,
+	`active_branch`,
+	`created_at`,
+	`updated_at`
+)
+SELECT
+	`old`.`chat_id`,
+	`ws`.`id`,
+	`old`.`active_repo`,
+	`old`.`active_branch`,
+	`old`.`created_at`,
+	`old`.`updated_at`
+FROM `group_workspaces__old` AS `old`
+JOIN `workspaces` AS `ws` ON `ws`.`path` = `old`.`workspace_path`;
+--> statement-breakpoint
+DROP TABLE `group_workspaces__old`;
diff --git a/drizzle/0013_workspace_active_state.sql b/drizzle/0013_workspace_active_state.sql
new file mode 100644
index 0000000..e61ad0f
--- /dev/null
+++ b/drizzle/0013_workspace_active_state.sql
@@ -0,0 +1,33 @@
+-- Move active_repo/active_branch from `group_workspaces` up to `workspaces`.
+-- Only one `.git/HEAD` exists per cloned repo, so the "active" state is a
+-- workspace-on-disk property, not a per-binding property. Multiple groups
+-- sharing a workspace should see the same active state.
+ALTER TABLE `workspaces` ADD `active_repo` text;--> statement-breakpoint
+ALTER TABLE `workspaces` ADD `active_branch` text;--> statement-breakpoint
+-- Backfill: for each workspace, copy the active state from any existing
+-- binding. Pre-migration each workspace maps 1:1 to a chat, so any binding
+-- row is authoritative; if a shared workspace somehow exists, prefer the
+-- most recently updated binding.
+UPDATE `workspaces`
+SET
+    `active_repo` = (
+        SELECT `gw`.`active_repo`
+        FROM `group_workspaces` AS `gw`
+        WHERE `gw`.`workspace_id` = `workspaces`.`id`
+        ORDER BY `gw`.`updated_at` DESC
+        LIMIT 1
+    ),
+    `active_branch` = (
+        SELECT `gw`.`active_branch`
+        FROM `group_workspaces` AS `gw`
+        WHERE `gw`.`workspace_id` = `workspaces`.`id`
+        ORDER BY `gw`.`updated_at` DESC
+        LIMIT 1
+    )
+WHERE EXISTS (
+    SELECT 1
+    FROM `group_workspaces` AS `gw`
+    WHERE `gw`.`workspace_id` = `workspaces`.`id`
+);--> statement-breakpoint
+ALTER TABLE `group_workspaces` DROP COLUMN `active_repo`;--> statement-breakpoint
+ALTER TABLE `group_workspaces` DROP COLUMN `active_branch`;
diff --git a/drizzle/0014_steady_korvac.sql b/drizzle/0014_steady_korvac.sql
new file mode 100644
index 0000000..4b7ecca
--- /dev/null
+++ b/drizzle/0014_steady_korvac.sql
@@ -0,0 +1,7 @@
+CREATE TABLE `feishu_bot_groups` (
+	`chat_id` text PRIMARY KEY NOT NULL,
+	`channel_id` text NOT NULL,
+	`chat_name` text NOT NULL,
+	`creator_open_id` text NOT NULL,
+	`created_at` integer NOT NULL
+);
diff --git a/drizzle/0015_closed_loki.sql b/drizzle/0015_closed_loki.sql
new file mode 100644
index 0000000..04ccaf8
--- /dev/null
+++ b/drizzle/0015_closed_loki.sql
@@ -0,0 +1 @@
+ALTER TABLE `feishu_threads` ADD `auto_respond` integer DEFAULT 0 NOT NULL;
\ No newline at end of file
diff --git a/drizzle/0016_fuzzy_gressill.sql b/drizzle/0016_fuzzy_gressill.sql
new file mode 100644
index 0000000..7bf9c49
--- /dev/null
+++ b/drizzle/0016_fuzzy_gressill.sql
@@ -0,0 +1,2 @@
+ALTER TABLE `workspaces` ADD `last_active_at` integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+UPDATE `workspaces` SET `last_active_at` = `updated_at`;
diff --git a/drizzle/meta/0010_snapshot.json b/drizzle/meta/0010_snapshot.json
index 5da7bb6..4fba971 100644
--- a/drizzle/meta/0010_snapshot.json
+++ b/drizzle/meta/0010_snapshot.json
@@ -248,4 +248,4 @@
   "internal": {
     "indexes": {}
   }
-}
\ No newline at end of file
+}
diff --git a/drizzle/meta/0011_snapshot.json b/drizzle/meta/0011_snapshot.json
new file mode 100644
index 0000000..296216d
--- /dev/null
+++ b/drizzle/meta/0011_snapshot.json
@@ -0,0 +1,317 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "9c5034a3-52eb-43ee-a6c8-f2d11a99d8b6",
+  "prevId": "44d9caba-533b-42eb-9eda-12fea8b19954",
+  "tables": {
+    "group_workspaces": {
+      "name": "group_workspaces",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_path": {
+          "name": "workspace_path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active_repo": {
+          "name": "active_repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "active_branch": {
+          "name": "active_branch",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_type": {
+          "name": "agent_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cwd": {
+          "name": "cwd",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "first_message": {
+          "name": "first_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "''"
+        },
+        "runner_session_id": {
+          "name": "runner_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "handoff": {
+          "name": "handoff",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": 0
+        },
+        "last_message_created_at": {
+          "name": "last_message_created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "scheduled_tasks": {
+      "name": "scheduled_tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instruction": {
+          "name": "instruction",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "schedule": {
+          "name": "schedule",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "tasks": {
+      "name": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "payload": {
+          "name": "payload",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_tasks_session_id": {
+          "name": "idx_tasks_session_id",
+          "columns": [
+            "session_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_threads": {
+      "name": "feishu_threads",
+      "columns": {
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/drizzle/meta/0012_snapshot.json b/drizzle/meta/0012_snapshot.json
new file mode 100644
index 0000000..a5d250b
--- /dev/null
+++ b/drizzle/meta/0012_snapshot.json
@@ -0,0 +1,370 @@
+{
+  "id": "224de30f-7d66-48ff-8940-1737e3db056e",
+  "prevId": "9c5034a3-52eb-43ee-a6c8-f2d11a99d8b6",
+  "version": "6",
+  "dialect": "sqlite",
+  "tables": {
+    "group_workspaces": {
+      "name": "group_workspaces",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active_repo": {
+          "name": "active_repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "active_branch": {
+          "name": "active_branch",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_type": {
+          "name": "agent_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cwd": {
+          "name": "cwd",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "first_message": {
+          "name": "first_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "''"
+        },
+        "runner_session_id": {
+          "name": "runner_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "handoff": {
+          "name": "handoff",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": 0
+        },
+        "last_message_created_at": {
+          "name": "last_message_created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "scheduled_tasks": {
+      "name": "scheduled_tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instruction": {
+          "name": "instruction",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "schedule": {
+          "name": "schedule",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "tasks": {
+      "name": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "payload": {
+          "name": "payload",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_tasks_session_id": {
+          "name": "idx_tasks_session_id",
+          "columns": [
+            "session_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_threads": {
+      "name": "feishu_threads",
+      "columns": {
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "workspaces": {
+      "name": "workspaces",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "path": {
+          "name": "path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "workspaces_path_unique": {
+          "name": "workspaces_path_unique",
+          "columns": [
+            "path"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/drizzle/meta/0013_snapshot.json b/drizzle/meta/0013_snapshot.json
new file mode 100644
index 0000000..5f9ec07
--- /dev/null
+++ b/drizzle/meta/0013_snapshot.json
@@ -0,0 +1,370 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "8d12163c-11da-4e53-b925-55107b8e5832",
+  "prevId": "224de30f-7d66-48ff-8940-1737e3db056e",
+  "tables": {
+    "group_workspaces": {
+      "name": "group_workspaces",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_type": {
+          "name": "agent_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cwd": {
+          "name": "cwd",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "first_message": {
+          "name": "first_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "''"
+        },
+        "runner_session_id": {
+          "name": "runner_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "handoff": {
+          "name": "handoff",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": 0
+        },
+        "last_message_created_at": {
+          "name": "last_message_created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "workspaces": {
+      "name": "workspaces",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "path": {
+          "name": "path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active_repo": {
+          "name": "active_repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "active_branch": {
+          "name": "active_branch",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "workspaces_path_unique": {
+          "name": "workspaces_path_unique",
+          "columns": [
+            "path"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "scheduled_tasks": {
+      "name": "scheduled_tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instruction": {
+          "name": "instruction",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "schedule": {
+          "name": "schedule",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "tasks": {
+      "name": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "payload": {
+          "name": "payload",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_tasks_session_id": {
+          "name": "idx_tasks_session_id",
+          "columns": [
+            "session_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_threads": {
+      "name": "feishu_threads",
+      "columns": {
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/drizzle/meta/0014_snapshot.json b/drizzle/meta/0014_snapshot.json
new file mode 100644
index 0000000..cb0d772
--- /dev/null
+++ b/drizzle/meta/0014_snapshot.json
@@ -0,0 +1,415 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "da37cbce-6bd1-4f48-8180-8f958e06cd7c",
+  "prevId": "8d12163c-11da-4e53-b925-55107b8e5832",
+  "tables": {
+    "group_workspaces": {
+      "name": "group_workspaces",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_type": {
+          "name": "agent_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cwd": {
+          "name": "cwd",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "first_message": {
+          "name": "first_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "''"
+        },
+        "runner_session_id": {
+          "name": "runner_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "handoff": {
+          "name": "handoff",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": 0
+        },
+        "last_message_created_at": {
+          "name": "last_message_created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "workspaces": {
+      "name": "workspaces",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "path": {
+          "name": "path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active_repo": {
+          "name": "active_repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "active_branch": {
+          "name": "active_branch",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "workspaces_path_unique": {
+          "name": "workspaces_path_unique",
+          "columns": [
+            "path"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "scheduled_tasks": {
+      "name": "scheduled_tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instruction": {
+          "name": "instruction",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "schedule": {
+          "name": "schedule",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "tasks": {
+      "name": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "payload": {
+          "name": "payload",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_tasks_session_id": {
+          "name": "idx_tasks_session_id",
+          "columns": [
+            "session_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_bot_groups": {
+      "name": "feishu_bot_groups",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "chat_name": {
+          "name": "chat_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "creator_open_id": {
+          "name": "creator_open_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_threads": {
+      "name": "feishu_threads",
+      "columns": {
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/drizzle/meta/0015_snapshot.json b/drizzle/meta/0015_snapshot.json
new file mode 100644
index 0000000..2048d09
--- /dev/null
+++ b/drizzle/meta/0015_snapshot.json
@@ -0,0 +1,423 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "53369f63-7a3f-4ee0-ad17-377fad384943",
+  "prevId": "da37cbce-6bd1-4f48-8180-8f958e06cd7c",
+  "tables": {
+    "group_workspaces": {
+      "name": "group_workspaces",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_type": {
+          "name": "agent_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cwd": {
+          "name": "cwd",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "first_message": {
+          "name": "first_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "''"
+        },
+        "runner_session_id": {
+          "name": "runner_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "handoff": {
+          "name": "handoff",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": 0
+        },
+        "last_message_created_at": {
+          "name": "last_message_created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "workspaces": {
+      "name": "workspaces",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "path": {
+          "name": "path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active_repo": {
+          "name": "active_repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "active_branch": {
+          "name": "active_branch",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "workspaces_path_unique": {
+          "name": "workspaces_path_unique",
+          "columns": [
+            "path"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "scheduled_tasks": {
+      "name": "scheduled_tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instruction": {
+          "name": "instruction",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "schedule": {
+          "name": "schedule",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "tasks": {
+      "name": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "payload": {
+          "name": "payload",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_tasks_session_id": {
+          "name": "idx_tasks_session_id",
+          "columns": [
+            "session_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_bot_groups": {
+      "name": "feishu_bot_groups",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "chat_name": {
+          "name": "chat_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "creator_open_id": {
+          "name": "creator_open_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_threads": {
+      "name": "feishu_threads",
+      "columns": {
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "auto_respond": {
+          "name": "auto_respond",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/drizzle/meta/0016_snapshot.json b/drizzle/meta/0016_snapshot.json
new file mode 100644
index 0000000..802131b
--- /dev/null
+++ b/drizzle/meta/0016_snapshot.json
@@ -0,0 +1,430 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "1c0c058a-c700-4e8a-b925-a2cd0e6f57dd",
+  "prevId": "53369f63-7a3f-4ee0-ad17-377fad384943",
+  "tables": {
+    "group_workspaces": {
+      "name": "group_workspaces",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "sessions": {
+      "name": "sessions",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "agent_type": {
+          "name": "agent_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "cwd": {
+          "name": "cwd",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "first_message": {
+          "name": "first_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "''"
+        },
+        "runner_session_id": {
+          "name": "runner_session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "handoff": {
+          "name": "handoff",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false,
+          "default": 0
+        },
+        "last_message_created_at": {
+          "name": "last_message_created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "workspaces": {
+      "name": "workspaces",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "path": {
+          "name": "path",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "active_repo": {
+          "name": "active_repo",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "active_branch": {
+          "name": "active_branch",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "last_active_at": {
+          "name": "last_active_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "workspaces_path_unique": {
+          "name": "workspaces_path_unique",
+          "columns": [
+            "path"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "scheduled_tasks": {
+      "name": "scheduled_tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "instruction": {
+          "name": "instruction",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "schedule": {
+          "name": "schedule",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "tasks": {
+      "name": "tasks",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "'pending'"
+        },
+        "payload": {
+          "name": "payload",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {
+        "idx_tasks_session_id": {
+          "name": "idx_tasks_session_id",
+          "columns": [
+            "session_id"
+          ],
+          "isUnique": false
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_bot_groups": {
+      "name": "feishu_bot_groups",
+      "columns": {
+        "chat_id": {
+          "name": "chat_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "channel_id": {
+          "name": "channel_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "chat_name": {
+          "name": "chat_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "creator_open_id": {
+          "name": "creator_open_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "feishu_threads": {
+      "name": "feishu_threads",
+      "columns": {
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "auto_respond": {
+          "name": "auto_respond",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": 0
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/drizzle/meta/_journal.json b/drizzle/meta/_journal.json
index bc1f2c5..054f025 100644
--- a/drizzle/meta/_journal.json
+++ b/drizzle/meta/_journal.json
@@ -78,6 +78,48 @@
       "when": 1778341150681,
       "tag": "0010_remarkable_malice",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "6",
+      "when": 1776319736541,
+      "tag": "0011_lean_enchantress",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1776407449569,
+      "tag": "0012_workspace_ids",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "6",
+      "when": 1776408029760,
+      "tag": "0013_workspace_active_state",
+      "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "6",
+      "when": 1776695439707,
+      "tag": "0014_steady_korvac",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1776842966838,
+      "tag": "0015_closed_loki",
+      "breakpoints": true
+    },
+    {
+      "idx": 16,
+      "version": "6",
+      "when": 1776932708363,
+      "tag": "0016_fuzzy_gressill",
+      "breakpoints": true
     }
   ]
-}
\ No newline at end of file
+}
diff --git a/package.json b/package.json
index 5061fca..9623a96 100644
--- a/package.json
+++ b/package.json
@@ -11,8 +11,9 @@
     "check:types": "tsc --noEmit",
     "clean:data": "rm -rf user-home/data && rm -rf user-home/sessions",
     "dev": "concurrently \"bun run dev:server\" \"bun run dev:web\"",
-    "dev:server": "bun run index.ts",
+    "dev:server": "bun --watch run index.ts",
     "dev:web": "cd web && bun run dev",
+    "start:server": "bun run index.ts",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "prepare": "husky"
@@ -47,6 +48,7 @@
     "hono": "^4.12.5",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "uuid": "^13.0.0"
+    "uuid": "^13.0.0",
+    "yaml": "^2.8.3"
   }
 }
\ No newline at end of file
diff --git a/scripts/down.sh b/scripts/down.sh
index 9877b02..71dab7a 100755
--- a/scripts/down.sh
+++ b/scripts/down.sh
@@ -8,15 +8,20 @@ GRACEFUL_WAIT_TICKS=10  # 10 × 0.5s = 5 seconds
 EXIT_CODE=0
 
 # Expected command patterns per process name
-declare -A EXPECTED_CMD
-EXPECTED_CMD[server]="bun run dev:server"
-EXPECTED_CMD[web]="bun run dev:web"
+expected_cmd_for() {
+  case "$1" in
+    server) echo "bun run start:server" ;;
+    web)    echo "bun run dev:web" ;;
+    *)      echo "" ;;
+  esac
+}
 
 # Verify PID belongs to the expected process
 is_our_process() {
   local pid="$1"
   local name="$2"
-  local expected="${EXPECTED_CMD[$name]:-}"
+  local expected
+  expected="$(expected_cmd_for "$name")"
 
   if [ -z "$expected" ]; then
     return 0  # no pattern to match, assume ours
@@ -30,6 +35,43 @@ is_our_process() {
   return 1
 }
 
+# Recursively collect a PID and all of its descendants, leaves first.
+# `bun run <script>` is a wrapper that spawns the real worker as a child;
+# killing only the tracked wrapper PID orphans that worker (it keeps the
+# Feishu connection alive on stale code). Walking the tree fixes that.
+collect_tree() {
+  local pid="$1"
+  local child
+  for child in $(pgrep -P "$pid" 2>/dev/null || true); do
+    collect_tree "$child"
+  done
+  echo "$pid"
+}
+
+# TERM a set of PIDs, wait for graceful exit, then KILL stragglers.
+kill_pids() {
+  local pids="$1"
+  [ -z "$pids" ] && return 0
+
+  local pid
+  for pid in $pids; do
+    kill "$pid" 2>/dev/null || true
+  done
+  for _ in $(seq 1 "$GRACEFUL_WAIT_TICKS"); do
+    local alive=false
+    for pid in $pids; do
+      if kill -0 "$pid" 2>/dev/null; then alive=true; fi
+    done
+    [ "$alive" = false ] && break
+    sleep 0.5
+  done
+  for pid in $pids; do
+    if kill -0 "$pid" 2>/dev/null; then
+      kill -9 "$pid" 2>/dev/null || true
+    fi
+  done
+}
+
 stop_process() {
   local name="$1"
   local pid_file="$RUN_DIR/$name.pid"
@@ -55,20 +97,11 @@ stop_process() {
     return
   fi
 
-  kill "$pid" 2>/dev/null || true
-  # Wait for graceful shutdown
-  for _ in $(seq 1 "$GRACEFUL_WAIT_TICKS"); do
-    if ! kill -0 "$pid" 2>/dev/null; then
-      break
-    fi
-    sleep 0.5
-  done
-  # Force kill if still running
-  if kill -0 "$pid" 2>/dev/null; then
-    kill -9 "$pid" 2>/dev/null || true
-    sleep 0.5
-  fi
-  # Final verification
+  # Kill the wrapper AND every descendant (the real worker lives below it).
+  local tree
+  tree="$(collect_tree "$pid")"
+  kill_pids "$tree"
+
   if kill -0 "$pid" 2>/dev/null; then
     echo "  $name: WARNING - failed to stop (PID: $pid)"
     EXIT_CODE=1
@@ -79,8 +112,59 @@ stop_process() {
   rm -f "$pid_file"
 }
 
+# True when PID's cwd is inside PROJECT_DIR, or its args reference it. Used to
+# scope the orphan sweep to THIS project so we never touch unrelated `bun run`
+# processes from other repos.
+proc_in_project() {
+  local pid="$1"
+  local cwd args
+  cwd="$(lsof -a -p "$pid" -d cwd -Fn 2>/dev/null | grep '^n' | cut -c2- || true)"
+  case "$cwd" in
+    "$PROJECT_DIR"|"$PROJECT_DIR"/*) return 0 ;;
+  esac
+  args="$(ps -p "$pid" -o args= 2>/dev/null || true)"
+  case "$args" in
+    *"$PROJECT_DIR"*) return 0 ;;
+  esac
+  return 1
+}
+
+# Sweep orphaned processes from earlier runs that aren't tracked by any PID
+# file (e.g. wrapper children reparented to init by previous buggy stops).
+# Matched by command pattern, then filtered to this project's cwd/args.
+sweep_orphans() {
+  local self=$$
+  local pattern pid candidates=""
+  for pattern in \
+    "bun run start:server" \
+    "bun run index.ts" \
+    "bun run dev:web" \
+    "bun run dev" \
+    "$PROJECT_DIR/web/node_modules/.bin/vite"
+  do
+    candidates="$candidates $(pgrep -f "$pattern" 2>/dev/null || true)"
+  done
+
+  local seen=" " killed=""
+  for pid in $candidates; do
+    [ "$pid" = "$self" ] && continue
+    case "$seen" in *" $pid "*) continue ;; esac
+    seen="$seen$pid "
+    kill -0 "$pid" 2>/dev/null || continue
+    if proc_in_project "$pid"; then
+      kill_pids "$(collect_tree "$pid")"
+      killed="$killed $pid"
+    fi
+  done
+
+  if [ -n "$killed" ]; then
+    echo "  swept orphaned processes:$killed"
+  fi
+}
+
 echo "Stopping Agentara..."
 stop_process "server"
 stop_process "web"
+sweep_orphans
 echo "Done."
 exit "$EXIT_CODE"
diff --git a/scripts/up.sh b/scripts/up.sh
index 57cd775..00445ea 100755
--- a/scripts/up.sh
+++ b/scripts/up.sh
@@ -33,7 +33,7 @@ echo "Starting Agentara in the background..."
 
 # Start backend server
 cd "$PROJECT_DIR"
-nohup bun run dev:server > "$LOG_DIR/server.log" 2>&1 &
+nohup bun run start:server > "$LOG_DIR/server.log" 2>&1 &
 SERVER_PID=$!
 sleep 1
 if ! kill -0 "$SERVER_PID" 2>/dev/null; then
diff --git a/src/boot-loader/boot-loader.ts b/src/boot-loader/boot-loader.ts
index ce53dda..de4665e 100644
--- a/src/boot-loader/boot-loader.ts
+++ b/src/boot-loader/boot-loader.ts
@@ -1,9 +1,11 @@
 import { execSync } from "node:child_process";
 import {
+  appendFileSync,
   existsSync,
   lstatSync,
   mkdirSync,
   mkdtempSync,
+  readFileSync,
   symlinkSync,
   writeFileSync,
 } from "node:fs";
@@ -21,10 +23,30 @@ class BootLoader {
    * Bootstraps the application by verifying the integrity and then igniting the kernel.
    */
   public async bootstrap(): Promise<void> {
+    this._installProcessGuards();
     await this._verifyIntegrity();
     await this._igniteKernel();
   }
 
+  /**
+   * Last-resort process guards. Without these, a single unhandled rejection
+   * or uncaught exception terminates this long-running service — e.g. one
+   * failed Feishu reply taking down the whole assistant. We log and stay
+   * alive; the real fix always belongs at the call site, but the service
+   * must not silently die.
+   */
+  private _installProcessGuards(): void {
+    process.on("unhandledRejection", (reason) => {
+      logger.error(
+        { err: reason },
+        "unhandled promise rejection (process kept alive)",
+      );
+    });
+    process.on("uncaughtException", (err) => {
+      logger.error({ err }, "uncaught exception (process kept alive)");
+    });
+  }
+
   private async _verifyIntegrity(): Promise<void> {
     if (!existsSync(config.paths.home)) {
       mkdirSync(config.paths.home, { recursive: true });
@@ -44,6 +66,15 @@ class BootLoader {
     if (!existsSync(config.paths.outputs)) {
       mkdirSync(config.paths.outputs, { recursive: true });
     }
+    if (!existsSync(config.paths.workspaces)) {
+      mkdirSync(config.paths.workspaces, { recursive: true });
+    }
+    if (!existsSync(config.paths.default_workspace)) {
+      mkdirSync(config.paths.default_workspace, { recursive: true });
+    }
+    if (!existsSync(config.paths.git_cache)) {
+      mkdirSync(config.paths.git_cache, { recursive: true });
+    }
 
     if (!existsSync(config.paths.memory)) {
       mkdirSync(config.paths.memory, { recursive: true });
@@ -57,12 +88,21 @@ class BootLoader {
         join(config.paths.claude_home, "settings.json"),
       );
     }
-    if (!existsSync(join(config.paths.home, "CLAUDE.md"))) {
+    const claudeMdPath = join(config.paths.home, "CLAUDE.md");
+    if (!existsSync(claudeMdPath)) {
       await downloadFile(
         "https://raw.githubusercontent.com/magiccube/agentara/main/user-home/CLAUDE.md",
-        join(config.paths.home, "CLAUDE.md"),
+        claudeMdPath,
       );
     }
+    if (!existsSync(config.paths.repos_md)) {
+      writeFileSync(config.paths.repos_md, REPOS_MD_TEMPLATE, "utf-8");
+      logger.info("Seeded $AGENTARA_HOME/REPOS.md with a starter template.");
+    }
+    // Keep CLAUDE.md pointed at REPOS.md so the agent sees the catalog +
+    // descriptions in context. Idempotent: only appends when the reference
+    // is missing, so user edits to CLAUDE.md are preserved.
+    this._ensureClaudeMdReferencesRepos(claudeMdPath);
     if (!existsSync(config.paths.skills)) {
       await downloadSkills();
     }
@@ -81,7 +121,9 @@ class BootLoader {
 agents:
   default:
     type: claude
-    model: claude-sonnet-4-6
+    # model: claude-sonnet-4-6   # optional; omit to use the CLI's default
+  codex:
+    isolate_host_env: false
 
 tasking:
   max_retries: 1
@@ -98,6 +140,45 @@ messaging:
     if (!existsSync(config.paths.data)) {
       mkdirSync(config.paths.data, { recursive: true });
     }
+
+    // Codex isolation (opt-in via `agents.codex.isolate_host_env`).
+    // When off, agentara-spawned Codex inherits the host `~/.codex`
+    // verbatim.  When on, agentara points Codex at its own
+    // CODEX_HOME so config / sessions / state / skills stay
+    // separate from the host's; auth.json is symlinked so the
+    // OAuth login is shared.  Nothing agentara does can prevent
+    // Codex from loading hooks from cwd ancestors under the real
+    // home — that problem lives in the host `~/.codex/hooks.json`
+    // placement itself.
+    if (config.agents.codex.isolate_host_env) {
+      if (!existsSync(config.paths.codex_home)) {
+        mkdirSync(config.paths.codex_home, { recursive: true });
+      }
+      this._ensureCodexAuthSymlink();
+    }
+  }
+
+  /**
+   * Append `@REPOS.md` to `$AGENTARA_HOME/CLAUDE.md` if it isn't already
+   * referenced. The reference lets Claude Code inline the repo catalog +
+   * descriptions into the agent's context via its native `@file` import.
+   * User edits to CLAUDE.md are preserved — we only append when missing.
+   */
+  private _ensureClaudeMdReferencesRepos(claudeMdPath: string): void {
+    try {
+      if (!existsSync(claudeMdPath)) return;
+      const body = readFileSync(claudeMdPath, "utf-8");
+      if (/^\s*@REPOS\.md\s*$/m.test(body)) return;
+      const needsNewline = body.length > 0 && !body.endsWith("\n");
+      appendFileSync(
+        claudeMdPath,
+        `${needsNewline ? "\n" : ""}\n@REPOS.md\n`,
+        "utf-8",
+      );
+      logger.info("Added `@REPOS.md` reference to CLAUDE.md.");
+    } catch (err) {
+      logger.warn({ err }, "Failed to ensure CLAUDE.md references REPOS.md");
+    }
   }
 
   /**
@@ -125,6 +206,40 @@ messaging:
     }
   }
 
+  /**
+   * Symlinks `$CODEX_HOME/auth.json` → `~/.codex/auth.json` so the
+   * isolated Codex home reuses the host login and OAuth token
+   * refresh stays bi-directional.  No-ops if the link already exists
+   * or the host has no auth file yet.
+   */
+  private _ensureCodexAuthSymlink(): void {
+    const hostAuth = join(config.paths.host_codex_home, "auth.json");
+    const linkPath = join(config.paths.codex_home, "auth.json");
+    try {
+      lstatSync(linkPath);
+      return;
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException)?.code !== "ENOENT") {
+        logger.warn({ err: e }, "Unexpected error checking Codex auth link");
+        return;
+      }
+    }
+    if (!existsSync(hostAuth)) {
+      logger.info(
+        "Host ~/.codex/auth.json not found — skipping Codex auth symlink",
+      );
+      return;
+    }
+    try {
+      symlinkSync(hostAuth, linkPath, "file");
+      logger.info(
+        "Created symlink $AGENTARA_HOME/.codex/auth.json → ~/.codex/auth.json",
+      );
+    } catch (err) {
+      logger.warn({ err }, "Failed to create Codex auth symlink");
+    }
+  }
+
   private async _igniteKernel(): Promise<void> {
     const { kernel } = await import("@/kernel");
     const logo = `\n▗▄▖  ▗▄▄▖▗▄▄▄▖▗▖  ▗▖▗▄▄▄▖▗▄▖ ▗▄▄▖  ▗▄▖
@@ -159,4 +274,34 @@ async function downloadSkills(): Promise<void> {
   execSync(`rm -rf ${tempDir}`);
 }
 
+const REPOS_MD_TEMPLATE = `# Predefined Repos
+
+<!--
+This file is the agent's repo knowledge base.
+
+- The \`/setup\` command parses each H2 section as a repo:
+    - title (\`## <name>\`)                → repo directory name
+    - \`- git_url: <url>\` bullet          → clone URL
+    - \`- description: <one-liner>\` bullet → short tagline shown on the card
+- Keep \`description\` to one short sentence — the card only needs a
+  quick label, not the full context.
+- Everything else in a section is free-form prose for the agent to read
+  via CLAUDE.md's \`@REPOS.md\` import. Feel free to update it as you
+  learn more about each repo.
+-->
+
+<!-- Example — delete or replace with your own entries:
+
+## agentara
+
+- git_url: https://github.com/magiccube/agentara.git
+- description: Bun + TypeScript personal assistant platform.
+
+Core flow is BootLoader → Kernel → Session/Task/Message. Useful when
+a group is discussing the assistant platform itself, session/task
+orchestration, or Feishu bot integration.
+
+-->
+`;
+
 export const bootLoader = new BootLoader();
diff --git a/src/community/anthropic/claude-agent-runner.ts b/src/community/anthropic/claude-agent-runner.ts
index 36c9b0f..f21d543 100644
--- a/src/community/anthropic/claude-agent-runner.ts
+++ b/src/community/anthropic/claude-agent-runner.ts
@@ -1,7 +1,14 @@
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 import {
   config,
   createLogger,
   extractTextContent,
+  inlineMentions,
   type MessageContent,
   type ToolMessage,
   type AgentRunner,
@@ -37,22 +44,45 @@ export class ClaudeAgentRunner implements AgentRunner {
     const isNew = options?.isNewSession ?? false;
     const signal = options?.signal;
     const textContentOfUserMessage = JSON.stringify(
-      extractTextContent(message),
+      inlineMentions(extractTextContent(message), message.mentions),
     );
 
+    const configuredModel = config.agents.default.model;
     const args = [
       "claude",
       ...(!isNew ? ["--resume", sessionId] : ["--session-id", sessionId]),
-      ...["--model", config.agents.default.model],
+      // Only pin the model when config names one; otherwise Claude CLI
+      // picks its own default (user omitted `model` in config.yaml).
+      ...(configuredModel ? ["--model", configuredModel] : []),
+      ...(options.dangerouslySkipPermissions
+        ? ["--dangerously-skip-permissions"]
+        : []),
       ...["--output-format", "stream-json"],
-      "--print",
-      "--verbose",
-      textContentOfUserMessage,
     ];
+
+    // Wire up the interactive permission MCP bridge when the inbound
+    // message carries a known Feishu user (chat_id + channel_id +
+    // sender_open_id) and the kernel has published its internal
+    // approval endpoint into the env. Otherwise fall back to Claude's
+    // default behavior (non-interactive, auto-deny for unapproved
+    // tools) so scheduled-task and non-Feishu paths aren't broken.
+    const permissionBridge = _buildPermissionBridge(message, options);
+    if (permissionBridge) {
+      args.push(
+        "--mcp-config",
+        permissionBridge.mcpConfigPath,
+        "--permission-prompt-tool",
+        "mcp__agentara__approve_tool_use",
+      );
+    }
+
+    args.push("--print", "--verbose", textContentOfUserMessage);
     const proc = Bun.spawn(args, {
       cwd: options.cwd,
       env: {
         ...Bun.env,
+        ...config.agents.env,
+        ...(options.envExtras ?? {}),
         ANTHROPIC_API_KEY: "",
       },
       stderr: "pipe",
@@ -113,6 +143,7 @@ export class ClaudeAgentRunner implements AgentRunner {
       if (signal) {
         signal.removeEventListener("abort", abortHandler);
       }
+      permissionBridge?.cleanup();
     }
 
     if (aborted) {
@@ -127,11 +158,14 @@ export class ClaudeAgentRunner implements AgentRunner {
           ? decoder.decode(Bun.concatArrayBuffers(stderrChunks))
           : "";
       const parts: string[] = [];
+      // stdout is the (already-parsed) stream-json — can be megabytes, so
+      // keep only a short tail where a trailing error result would land.
+      // stderr carries the actual failure reason, so allow it more room.
       if (stdoutRaw.trim()) {
-        parts.push(`Stdout:\n${stdoutRaw.trim()}`);
+        parts.push(`Stdout:\n${_clipTail(stdoutRaw.trim(), 800)}`);
       }
       if (stderrText.trim()) {
-        parts.push(`Stderr:\n${stderrText.trim()}`);
+        parts.push(`Stderr:\n${_clipTail(stderrText.trim(), 3000)}`);
       }
       const detail = parts.length > 0 ? `\n\n${parts.join("\n\n")}` : "";
       throw new Error(`Claude Code exited with code ${exitCode}${detail}`);
@@ -165,6 +199,30 @@ export class ClaudeAgentRunner implements AgentRunner {
           role,
           content: obj.message.content,
         };
+        // Carry token usage + resolved model on assistant turns so
+        // downstream consumers can surface context-window occupancy and
+        // which model served the turn. Claude streams both on each
+        // `assistant` event under `message.usage` / `message.model`.
+        if (role === "assistant") {
+          if (obj.message?.usage) {
+            const u = obj.message.usage;
+            (message as AssistantMessage).usage = {
+              input_tokens: u.input_tokens,
+              output_tokens: u.output_tokens,
+              cache_read_input_tokens: u.cache_read_input_tokens,
+              cache_creation_input_tokens: u.cache_creation_input_tokens,
+            };
+          }
+          // Skip Claude's `<synthetic>` placeholder model (compaction
+          // notices and other locally-generated messages) so it never
+          // leaks into the displayed model name.
+          if (
+            typeof obj.message?.model === "string" &&
+            obj.message.model !== "<synthetic>"
+          ) {
+            (message as AssistantMessage).model = obj.message.model;
+          }
+        }
         return message;
       }
       return null;
@@ -177,3 +235,84 @@ export class ClaudeAgentRunner implements AgentRunner {
 function containsToolResult(message: { content: MessageContent[] }): boolean {
   return message.content.some((content) => content.type === "tool_result");
 }
+
+/**
+ * Keep only the trailing `maxChars` of `text` (errors surface at the end),
+ * prefixing a marker noting how much was dropped. Returns `text` unchanged
+ * when it already fits.
+ */
+function _clipTail(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const dropped = text.length - maxChars;
+  return `… [${dropped} chars truncated]\n${text.slice(-maxChars)}`;
+}
+
+interface PermissionBridge {
+  mcpConfigPath: string;
+  cleanup: () => void;
+}
+
+function _buildPermissionBridge(
+  message: UserMessage,
+  options: AgentRunOptions,
+): PermissionBridge | null {
+  if (options.dangerouslySkipPermissions) return null;
+  const chatId = message.chat_id;
+  const channelId = message.channel_id;
+  const initiatorOpenId = message.sender_open_id;
+  const approvalUrl = Bun.env.AGENTARA_PERMISSION_URL;
+  const approvalToken = Bun.env.AGENTARA_PERMISSION_TOKEN;
+  if (!chatId || !channelId || !initiatorOpenId) return null;
+  if (!approvalUrl || !approvalToken) return null;
+
+  const scriptPath = _resolveMcpScriptPath();
+  const mcpConfig = {
+    mcpServers: {
+      agentara: {
+        command: "bun",
+        args: ["run", scriptPath],
+        env: {
+          AGENTARA_APPROVAL_URL: approvalUrl,
+          AGENTARA_APPROVAL_TOKEN: approvalToken,
+          AGENTARA_SESSION_ID: message.session_id,
+          AGENTARA_CHANNEL_ID: channelId,
+          AGENTARA_CHAT_ID: chatId,
+          AGENTARA_INITIATOR_OPEN_ID: initiatorOpenId,
+          AGENTARA_REPLY_TO_MESSAGE_ID: message.id ?? "",
+        },
+      },
+    },
+  };
+  const dir = mkdtempSync(join(tmpdir(), "agentara-claude-mcp-"));
+  const mcpConfigPath = join(dir, `mcp-${randomUUID()}.json`);
+  writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig));
+  return {
+    mcpConfigPath,
+    cleanup: () => {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch (err) {
+        logger.warn(
+          { err, dir },
+          "failed to clean up temp mcp-config dir",
+        );
+      }
+    },
+  };
+}
+
+/**
+ * Absolute path to the stdio MCP server script. Resolved relative to
+ * this file so it works both under `bun --watch run index.ts` (dev)
+ * and from a bundled JS build where `import.meta.url` still points
+ * inside the output dir.
+ *
+ * When shipping a `bun --compile` binary the .ts source won't exist
+ * at that path at runtime — the caller would need to either keep the
+ * source alongside the binary or switch to an inlined-string strategy.
+ * Leaving a clear breadcrumb rather than silently failing.
+ */
+function _resolveMcpScriptPath(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, "permission-mcp-server.ts");
+}
diff --git a/src/community/anthropic/claude-usage.ts b/src/community/anthropic/claude-usage.ts
new file mode 100644
index 0000000..a5b76f9
--- /dev/null
+++ b/src/community/anthropic/claude-usage.ts
@@ -0,0 +1,128 @@
+import { createLogger } from "@/shared";
+
+const logger = createLogger("claude-usage");
+
+/**
+ * Account-level Claude usage snapshot returned by the Anthropic OAuth
+ * usage endpoint. `utilization` values are percentages (`0..100`).
+ */
+export interface ClaudeUsage {
+  five_hour: {
+    utilization: number;
+    resets_at: string | null;
+  };
+  seven_day: {
+    utilization: number;
+    resets_at: string;
+  };
+  extra_usage:
+    | {
+        is_enabled: true;
+        monthly_limit: number;
+        used_credits: number;
+        utilization: number;
+      }
+    | {
+        is_enabled: false;
+        monthly_limit: null;
+        used_credits: null;
+        utilization: null;
+      };
+}
+
+/**
+ * Reads Claude Code credentials from the macOS Keychain via
+ * `security find-generic-password`. Returns the stored value (a JSON
+ * string) parsed as an object.
+ */
+async function getClaudeCredentials() {
+  const proc = Bun.spawn(
+    ["security", "find-generic-password", "-s", "Claude Code-credentials", "-w"],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exit = await proc.exited;
+  if (exit !== 0) {
+    logger.warn({ exit, stderr }, "security find-generic-password failed");
+    throw new Error(stderr || `security command exited with code ${exit}`);
+  }
+  const trimmed = stdout.trim();
+  if (!trimmed) {
+    throw new Error("empty credentials from keychain");
+  }
+  return JSON.parse(trimmed) as {
+    claudeAiOauth: {
+      accessToken: string;
+      refreshToken: string;
+      expiresAt: number;
+    };
+  };
+}
+
+/**
+ * Fetches the current Claude usage / rate-limit snapshot from the
+ * Anthropic OAuth usage endpoint using the locally stored subscription
+ * credentials. Throws when credentials are missing or the request fails.
+ */
+export async function queryClaudeUsage(): Promise<ClaudeUsage> {
+  const credentials = await getClaudeCredentials();
+  const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
+    headers: new Headers({
+      "anthropic-beta": "oauth-2025-04-20",
+      Authorization: `Bearer ${credentials.claudeAiOauth.accessToken}`,
+    }),
+  });
+  return (await response.json()) as ClaudeUsage;
+}
+
+interface UsageCacheEntry {
+  at: number;
+  data: ClaudeUsage;
+}
+let _usageCache: UsageCacheEntry | null = null;
+
+/**
+ * Cached variant of {@link queryClaudeUsage} for hot paths like rendering
+ * a card footer on every reply. Serves a cached snapshot within `ttlMs`,
+ * and on failure falls back to the last good snapshot (or `null`) instead
+ * of throwing — the footer is best-effort and must never break a reply.
+ *
+ * @param ttlMs - Cache lifetime in milliseconds (default 60s).
+ */
+export async function getClaudeUsageCached(
+  ttlMs = 60_000,
+): Promise<ClaudeUsage | null> {
+  const now = Date.now();
+  if (_usageCache && now - _usageCache.at < ttlMs) {
+    return _usageCache.data;
+  }
+  try {
+    const data = await queryClaudeUsage();
+    _usageCache = { at: now, data };
+    return data;
+  } catch (err) {
+    logger.warn({ err }, "failed to query Claude usage; using last snapshot");
+    return _usageCache?.data ?? null;
+  }
+}
+
+/** Long-context ("1M") Claude window, in tokens. */
+export const LONG_CONTEXT_TOKENS = 1_000_000;
+
+/**
+ * Context-window size (in tokens) assumed for the assistant's turns. The
+ * configured models run on the 1M long-context window (the model id can't
+ * be reliably mapped to a window — the config often leaves it unpinned and
+ * the `1m` variant isn't reflected in the name), so we default to 1M. This
+ * keeps the occupancy denominator stable across a whole conversation
+ * instead of jumping mid-session.
+ *
+ * @param model - Resolved model id, accepted for forward-compat; unused.
+ */
+// eslint-disable-next-line no-unused-vars
+export function contextLimitForModel(model?: string): number {
+  return LONG_CONTEXT_TOKENS;
+}
diff --git a/src/community/anthropic/index.ts b/src/community/anthropic/index.ts
index acdafb8..1c396c9 100644
--- a/src/community/anthropic/index.ts
+++ b/src/community/anthropic/index.ts
@@ -1 +1,2 @@
 export * from "./claude-agent-runner";
+export * from "./claude-usage";
diff --git a/src/community/anthropic/permission-mcp-server.ts b/src/community/anthropic/permission-mcp-server.ts
new file mode 100644
index 0000000..efd6b40
--- /dev/null
+++ b/src/community/anthropic/permission-mcp-server.ts
@@ -0,0 +1,241 @@
+/**
+ * Standalone stdio MCP server spawned by Claude Code as the
+ * `--permission-prompt-tool` backend.
+ *
+ * The Claude CLI invokes `approve_tool_use` before running any tool
+ * that would normally need interactive approval. This server:
+ *
+ * 1. Receives the JSON-RPC `tools/call` request on stdin.
+ * 2. Forwards it (plus the per-session context baked into the spawn
+ *    env) to the kernel's `/internal/permission/request` endpoint.
+ * 3. Blocks on the kernel's long-poll response (the kernel sends an
+ *    approve/deny card to Feishu and waits up to 5 min).
+ * 4. Returns the decision as a single `text` content block in the
+ *    shape Claude expects:
+ *      `{"behavior":"allow","updatedInput":{…}}`
+ *      or
+ *      `{"behavior":"deny","message":"…"}`.
+ *
+ * This file is intentionally self-contained — it runs in its own
+ * subprocess launched by Claude, not inside the kernel's runtime.
+ * Do NOT import from `@/...` here; the import alias is not resolved
+ * for ad-hoc `bun run <file>` subprocess invocations spawned via
+ * `.mcp.json`.
+ */
+
+interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: number | string | null;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number | string | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+const PROTOCOL_VERSION = "2024-11-05";
+const TOOL_NAME = "approve_tool_use";
+
+function _env(key: string, required = true): string {
+  const v = process.env[key];
+  if ((!v || v.length === 0) && required) {
+    _writeToStderr(`[permission-mcp] missing required env: ${key}`);
+    process.exit(1);
+  }
+  return v ?? "";
+}
+
+function _writeToStderr(line: string): void {
+  try {
+    process.stderr.write(line + "\n");
+  } catch {
+    // ignore
+  }
+}
+
+function _writeResponse(resp: JsonRpcResponse): void {
+  process.stdout.write(JSON.stringify(resp) + "\n");
+}
+
+function _buildInitializeResult(): Record<string, unknown> {
+  return {
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: {
+      tools: {},
+    },
+    serverInfo: {
+      name: "agentara-permission",
+      version: "0.1.0",
+    },
+  };
+}
+
+function _buildToolsListResult(): Record<string, unknown> {
+  return {
+    tools: [
+      {
+        name: TOOL_NAME,
+        description:
+          "Approve or deny a Claude Code tool use by forwarding the request " +
+          "to the agentara kernel, which asks the human via a Feishu card.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            tool_name: { type: "string" },
+            input: { type: "object", additionalProperties: true },
+            tool_use_id: { type: "string" },
+          },
+          required: ["tool_name", "input"],
+          additionalProperties: true,
+        },
+      },
+    ],
+  };
+}
+
+async function _handleToolsCall(
+  args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const toolName =
+    typeof args.tool_name === "string" ? args.tool_name : "(unknown)";
+  const toolInput =
+    args.input && typeof args.input === "object"
+      ? (args.input as Record<string, unknown>)
+      : {};
+
+  const approvalUrl = _env("AGENTARA_APPROVAL_URL");
+  const approvalToken = _env("AGENTARA_APPROVAL_TOKEN");
+  const body = {
+    session_id: _env("AGENTARA_SESSION_ID"),
+    channel_id: _env("AGENTARA_CHANNEL_ID"),
+    chat_id: _env("AGENTARA_CHAT_ID"),
+    initiator_open_id: _env("AGENTARA_INITIATOR_OPEN_ID"),
+    reply_to_message_id: _env("AGENTARA_REPLY_TO_MESSAGE_ID", false) || undefined,
+    tool_name: toolName,
+    tool_input: toolInput,
+  };
+
+  let decisionText: string;
+  try {
+    const res = await fetch(approvalUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${approvalToken}`,
+      },
+      body: JSON.stringify(body),
+      // Bun's fetch supports no default timeout; the kernel already
+      // caps the wait at 5 min + small buffer, and the subprocess is
+      // single-purpose so a stuck request just blocks this tool call.
+    });
+    if (!res.ok) {
+      throw new Error(`kernel returned HTTP ${res.status}`);
+    }
+    // We pass the kernel's JSON body through verbatim as the Claude
+    // permission tool's text content — the shape already matches
+    // `{behavior, updatedInput|message}`.
+    decisionText = await res.text();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    _writeToStderr(`[permission-mcp] kernel call failed: ${message}`);
+    decisionText = JSON.stringify({
+      behavior: "deny",
+      message: `Permission bridge failed: ${message}`,
+    });
+  }
+
+  return {
+    content: [{ type: "text", text: decisionText }],
+  };
+}
+
+async function _handleRequest(req: JsonRpcRequest): Promise<void> {
+  const id = req.id ?? null;
+  try {
+    switch (req.method) {
+      case "initialize":
+        _writeResponse({ jsonrpc: "2.0", id, result: _buildInitializeResult() });
+        return;
+      case "notifications/initialized":
+        // Notifications have no id and no response.
+        return;
+      case "tools/list":
+        _writeResponse({ jsonrpc: "2.0", id, result: _buildToolsListResult() });
+        return;
+      case "tools/call": {
+        const params = (req.params ?? {}) as {
+          name?: string;
+          arguments?: Record<string, unknown>;
+        };
+        if (params.name !== TOOL_NAME) {
+          _writeResponse({
+            jsonrpc: "2.0",
+            id,
+            error: {
+              code: -32601,
+              message: `unknown tool: ${String(params.name)}`,
+            },
+          });
+          return;
+        }
+        const result = await _handleToolsCall(params.arguments ?? {});
+        _writeResponse({ jsonrpc: "2.0", id, result });
+        return;
+      }
+      case "ping":
+        _writeResponse({ jsonrpc: "2.0", id, result: {} });
+        return;
+      default:
+        if (req.id !== undefined && req.id !== null) {
+          _writeResponse({
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32601, message: `method not found: ${req.method}` },
+          });
+        }
+        return;
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    _writeToStderr(`[permission-mcp] handler error: ${message}`);
+    if (req.id !== undefined && req.id !== null) {
+      _writeResponse({
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32603, message },
+      });
+    }
+  }
+}
+
+async function _main(): Promise<void> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of process.stdin as unknown as AsyncIterable<Buffer>) {
+    buffer += decoder.decode(chunk, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const raw of lines) {
+      const line = raw.trim();
+      if (!line) continue;
+      let parsed: JsonRpcRequest;
+      try {
+        parsed = JSON.parse(line) as JsonRpcRequest;
+      } catch {
+        _writeToStderr(`[permission-mcp] malformed line: ${line.slice(0, 200)}`);
+        continue;
+      }
+      await _handleRequest(parsed);
+    }
+  }
+}
+
+void _main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  _writeToStderr(`[permission-mcp] fatal: ${message}`);
+  process.exit(1);
+});
diff --git a/src/community/feishu/messaging/data/schema.ts b/src/community/feishu/messaging/data/schema.ts
index 5fb79ff..ab8b439 100644
--- a/src/community/feishu/messaging/data/schema.ts
+++ b/src/community/feishu/messaging/data/schema.ts
@@ -15,4 +15,31 @@ export const feishuThreads = sqliteTable("feishu_threads", {
   session_id: text("session_id").notNull(),
   /** Epoch milliseconds when the mapping was created. */
   created_at: integer("created_at").notNull(),
+  /**
+   * When 1, every message inside this thread triggers the bot without
+   * requiring an @-mention. When 0 (default), group-chat messages must
+   * still @-mention the bot even inside a thread the bot already
+   * participates in. Toggle via `/unmute` / `/mute` in the thread.
+   */
+  auto_respond: integer("auto_respond").notNull().default(0),
+});
+
+/**
+ * Groups the bot itself created via the `/group` command.
+ *
+ * Used by `/ungroup` to (a) authorize dismissal — only the original
+ * creator can tear down a group the bot made, and (b) look up groups by
+ * name when the command runs in P2P without a current-chat context.
+ */
+export const feishuBotGroups = sqliteTable("feishu_bot_groups", {
+  /** Feishu chat_id of the group created by the bot. */
+  chat_id: text("chat_id").primaryKey(),
+  /** Channel id that created the group (for multi-channel deployments). */
+  channel_id: text("channel_id").notNull(),
+  /** Display name given to the group at creation time. */
+  chat_name: text("chat_name").notNull(),
+  /** open_id of the user who ran `/group` — authoritative for dismissal. */
+  creator_open_id: text("creator_open_id").notNull(),
+  /** Epoch milliseconds when the group was created. */
+  created_at: integer("created_at").notNull(),
 });
diff --git a/src/community/feishu/messaging/message-channel.ts b/src/community/feishu/messaging/message-channel.ts
index 752580c..1523312 100644
--- a/src/community/feishu/messaging/message-channel.ts
+++ b/src/community/feishu/messaging/message-channel.ts
@@ -12,14 +12,20 @@ import {
   createLogger,
   uuid,
   type AssistantMessage,
+  type CardActionPayload,
+  type CardFooterStats,
   type MessageChannel,
   type MessageChannelEventTypes,
   type UserMessage,
 } from "@/shared";
 
-import { feishuThreads } from "./data";
-import { renderMessageCard, splitMarkdownByTables } from "./message-renderer";
-import type { MessageReceiveEventData } from "./types";
+
+import { feishuBotGroups, feishuThreads } from "./data";
+import {
+  renderMessageCard,
+  splitMarkdownForCards,
+} from "./message-renderer";
+import type { Card, MessageReceiveEventData } from "./types";
 import { convertPostToMarkdown } from "./utils";
 
 function _isFeishuBadRequestError(err: unknown): boolean {
@@ -56,12 +62,62 @@ export class FeishuMessageChannel
   private _inboundClient: WSClient;
   private _client: Client;
   private _db: DrizzleDB;
+  /**
+   * Optional workspace resolver injected by the kernel. Given a Feishu
+   * `chat_id`, returns the absolute cwd of the workspace bound to that
+   * chat (or the default workspace when unbound). Used as the download
+   * root for user-uploaded files & quoted resources so each bound chat
+   * keeps its artifacts inside its own workspace instead of a global
+   * pool.
+   */
+  // eslint-disable-next-line no-unused-vars
+  private _resolveWorkspaceCwd?: (chatId: string | undefined) => string;
+  /**
+   * Optional session-cwd resolver injected by the kernel. Given a session id,
+   * returns the absolute cwd that session's agent ran in — the precise base
+   * for resolving outbound relative paths, since a single channel sends
+   * replies for many chats and `config.chatId` alone is not enough.
+   */
+  // eslint-disable-next-line no-unused-vars
+  private _resolveSessionCwd?: (sessionId: string) => string | undefined;
   private _failedCardUpdateMessages = new Set<string>();
+  /**
+   * Primary message ids for which we've already posted the final
+   * markdown-continuation cards. Kept so that a repeat `streaming: false`
+   * update doesn't double-post continuations.
+   */
+  private _finalizedPrimaries = new Set<string>();
+  /**
+   * Wall-clock start timestamps of in-flight streaming cards, keyed by
+   * primary message id. Set when the first streaming reply is created and
+   * consumed on the final (`streaming: false`) patch so we can render a
+   * "Done in Xs" note at the bottom of the finalized card.
+   */
+  private _cardStartedAt = new Map<string, number>();
   private _logger: Logger;
+  private _requireMention: boolean;
+  private _botOpenId?: string;
+
+  /**
+   * Bot's own open_id as resolved at `start()`. `undefined` until the channel
+   * has started, and when `require_mention` is disabled the bot-info fetch
+   * is skipped so this stays undefined even post-start.
+   */
+  get botOpenId(): string | undefined {
+    return this._botOpenId;
+  }
+  private _allowedUserOpenIds?: Set<string>;
+  private _allowedUserEmails?: string[];
 
   /**
    * Create a Feishu message channel.
-   * @param config - Feishu app credentials (defaults to env vars).
+   * @param config - Feishu app credentials, plus optional inbound filters:
+   *   - `requireMention`: when true, group-chat messages must @mention the bot.
+   *     The bot's own open_id is resolved at `start()` via `/bot/v3/info`. P2P
+   *     messages bypass the check — they are obviously directed at the bot.
+   *   - `allowedUserOpenIds` / `allowedUserEmails`: when either is non-empty,
+   *     the sender's open_id must be in the union of the two sets. Emails are
+   *     resolved to open_ids at `start()` via `/contact/v3/users/batch_get_id`.
    * @param db - Drizzle database instance for persisting thread-to-session mappings.
    */
   constructor(
@@ -70,6 +126,13 @@ export class FeishuMessageChannel
       chatId: string;
       appId: string;
       appSecret: string;
+      requireMention?: boolean;
+      allowedUserOpenIds?: string[];
+      allowedUserEmails?: string[];
+      // eslint-disable-next-line no-unused-vars
+      resolveWorkspaceCwd?: (chatId: string | undefined) => string;
+      // eslint-disable-next-line no-unused-vars
+      resolveSessionCwd?: (sessionId: string) => string | undefined;
     },
     db: DrizzleDB,
   ) {
@@ -80,6 +143,15 @@ export class FeishuMessageChannel
     }
     this._db = db;
     this._logger = createLogger("feishu-message-channel");
+    this._requireMention = !!config.requireMention;
+    this._resolveWorkspaceCwd = config.resolveWorkspaceCwd;
+    this._resolveSessionCwd = config.resolveSessionCwd;
+    if (config.allowedUserOpenIds && config.allowedUserOpenIds.length > 0) {
+      this._allowedUserOpenIds = new Set(config.allowedUserOpenIds);
+    }
+    if (config.allowedUserEmails && config.allowedUserEmails.length > 0) {
+      this._allowedUserEmails = config.allowedUserEmails;
+    }
     this._inboundClient = new WSClient({
       appId: this.config.appId,
       appSecret: this.config.appSecret,
@@ -92,104 +164,554 @@ export class FeishuMessageChannel
 
   /** Start listening for inbound messages via WebSocket. */
   async start() {
+    const needsToken = this._requireMention || !!this._allowedUserEmails;
+    const tenantToken = needsToken ? await this._fetchTenantAccessToken() : null;
+
+    if (this._requireMention && tenantToken) {
+      this._botOpenId = await this._fetchBotOpenId(tenantToken);
+      this._logger.info(
+        { bot_open_id: this._botOpenId },
+        "resolved bot open_id for @mention filtering",
+      );
+    }
+
+    if (this._allowedUserEmails && tenantToken) {
+      const resolved = await this._resolveEmailsToOpenIds(
+        this._allowedUserEmails,
+        tenantToken,
+      );
+      if (!this._allowedUserOpenIds) {
+        this._allowedUserOpenIds = new Set();
+      }
+      for (const openId of resolved.values()) {
+        this._allowedUserOpenIds.add(openId);
+      }
+      const unresolved = this._allowedUserEmails.filter(
+        (e) => !resolved.has(e),
+      );
+      this._logger.info(
+        {
+          resolved_count: resolved.size,
+          unresolved,
+          total_whitelist: this._allowedUserOpenIds.size,
+        },
+        "resolved email whitelist to open_ids",
+      );
+      if (unresolved.length > 0) {
+        this._logger.warn(
+          { unresolved },
+          "some whitelisted emails could not be resolved to an open_id",
+        );
+      }
+    }
+
+    // The node-sdk's `IHandles` type doesn't include card-action events, but
+    // the underlying `EventDispatcher.invoke` dispatches by event-type string,
+    // and the WS gateway delivers `card.action.trigger` alongside regular
+    // events for self-built Feishu apps. We cast through `as never` to bypass
+    // the typing gap without loosening the strict lookup of typed handlers.
     await this._inboundClient.start({
       eventDispatcher: new EventDispatcher({}).register({
         "im.message.receive_v1": this._handleMessageReceive,
         "im.message.recalled_v1": this._handleMessageRecall,
+        ["card.action.trigger" as never]: this
+          ._handleCardAction as never,
       }),
     });
   }
 
-  /** Reply to a message in a Feishu chat thread. */
+  /**
+   * Send a raw Feishu interactive card to a chat. Escape hatch used by
+   * commands that render custom cards (e.g. `/setup`) outside the normal
+   * AssistantMessage pipeline. Returns the posted message's id so the caller
+   * can correlate later card actions / updates.
+   *
+   * `options.replyInThread` defaults to `false`: command-originated cards
+   * should appear inline in the chat rather than opening a new topic. Pass
+   * `true` explicitly if the flow is session-scoped.
+   */
+  async sendRawCard(
+    chatId: string,
+    card: Card,
+    options: { replyTo?: string; replyInThread?: boolean } = {},
+  ): Promise<string> {
+    if (options.replyTo) {
+      const { data } = await this._client.im.message.reply({
+        path: { message_id: options.replyTo },
+        data: {
+          msg_type: "interactive",
+          content: JSON.stringify(card),
+          reply_in_thread: options.replyInThread ?? false,
+        },
+      });
+      if (!data?.message_id) {
+        throw new Error("Failed to reply with interactive card");
+      }
+      return data.message_id;
+    }
+    const { data } = await this._client.im.message.create({
+      params: { receive_id_type: "chat_id" },
+      data: {
+        receive_id: chatId,
+        msg_type: "interactive",
+        content: JSON.stringify(card),
+      },
+    });
+    if (!data?.message_id) {
+      throw new Error("Failed to post interactive card");
+    }
+    return data.message_id;
+  }
+
+  /**
+   * Best-effort fetch of a chat's display name. The bot must be a member of
+   * the chat, with `im:chat` or `im:chat:readonly` scope. Returns undefined
+   * on any failure (permission denied, chat not found, network error) so
+   * callers can fall back to a deterministic default.
+   */
+  async getChatName(chatId: string): Promise<string | undefined> {
+    try {
+      const { data } = await this._client.im.chat.get({
+        path: { chat_id: chatId },
+      });
+      const name =
+        data?.i18n_names?.zh_cn ?? data?.name ?? data?.i18n_names?.en_us;
+      return typeof name === "string" && name.trim() ? name.trim() : undefined;
+    } catch (err) {
+      this._logger.warn({ err, chat_id: chatId }, "getChatName failed");
+      return undefined;
+    }
+  }
+
+  /**
+   * Replace the content of an existing interactive card message. Used by
+   * card-driven flows to transition the same message from "pending" to
+   * "completed" without spawning a new reply.
+   */
+  async updateRawCard(messageId: string, card: Card): Promise<void> {
+    await this._client.im.message.patch({
+      path: { message_id: messageId },
+      data: { content: JSON.stringify(card) },
+    });
+  }
+
+  /**
+   * Post a plain-text message into an arbitrary chat. Returns the posted
+   * message's id so callers can anchor follow-up replies (e.g. `/group`
+   * sends a welcome line then anchors its `/setup` card as a reply to it).
+   *
+   * Distinct from `postMessage(AssistantMessage)` which renders a card to
+   * this channel's default `config.chatId`.
+   */
+  async sendPlainText(chatId: string, text: string): Promise<string> {
+    const { data } = await this._client.im.message.create({
+      params: { receive_id_type: "chat_id" },
+      data: {
+        receive_id: chatId,
+        msg_type: "text",
+        content: JSON.stringify({ text }),
+      },
+    });
+    if (!data?.message_id) {
+      throw new Error("Failed to post plain text message");
+    }
+    return data.message_id;
+  }
+
+  /**
+   * Create a new group chat. The bot itself ends up as the initial owner;
+   * callers that want a human owner should follow up with
+   * {@link transferChatOwner}. `memberOpenIds` are added at creation time so
+   * no separate add-members round-trip is needed.
+   *
+   * Requires the `im:chat:create` scope.
+   */
+  async createChat(options: {
+    name: string;
+    memberOpenIds: string[];
+    description?: string;
+  }): Promise<string> {
+    const { data } = await this._client.im.chat.create({
+      params: { user_id_type: "open_id" },
+      data: {
+        name: options.name,
+        description: options.description,
+        chat_type: "private",
+        user_id_list: options.memberOpenIds,
+      },
+    });
+    if (!data?.chat_id) {
+      throw new Error("Feishu returned no chat_id when creating the chat");
+    }
+    return data.chat_id;
+  }
+
+  /**
+   * Transfer a group's owner to the specified user. The bot must currently
+   * be the owner. Requires the `im:chat.owner:update` scope.
+   */
+  async transferChatOwner(
+    chatId: string,
+    ownerOpenId: string,
+  ): Promise<void> {
+    await this._client.im.chat.update({
+      path: { chat_id: chatId },
+      params: { user_id_type: "open_id" },
+      data: { owner_id: ownerOpenId },
+    });
+  }
+
+  /**
+   * Dissolve a chat. Requires the bot to be the owner. Used by `/ungroup`
+   * to tear down groups the bot created earlier.
+   */
+  async dismissChat(chatId: string): Promise<void> {
+    await this._client.im.chat.delete({
+      path: { chat_id: chatId },
+    });
+  }
+
+  /**
+   * Look up a bot-created group by its chat_id. Returns undefined when the
+   * chat was not created by this bot (e.g. an existing group the bot was
+   * just added to).
+   */
+  findBotGroup(chatId: string):
+    | { chat_id: string; chat_name: string; creator_open_id: string }
+    | undefined {
+    const row = this._db
+      .select({
+        chat_id: feishuBotGroups.chat_id,
+        chat_name: feishuBotGroups.chat_name,
+        creator_open_id: feishuBotGroups.creator_open_id,
+      })
+      .from(feishuBotGroups)
+      .where(eq(feishuBotGroups.chat_id, chatId))
+      .get();
+    return row ?? undefined;
+  }
+
+  /**
+   * Find a bot-created group by either its display name or chat_id, scoped
+   * to a single creator. Used by `/ungroup <query>` from P2P so users can
+   * only dismiss groups they themselves created. Name match is exact
+   * (multiple groups may share a name; the caller must disambiguate).
+   */
+  findBotGroupForCreator(
+    query: string,
+    creatorOpenId: string,
+  ): Array<{ chat_id: string; chat_name: string }> {
+    return this._db
+      .select({
+        chat_id: feishuBotGroups.chat_id,
+        chat_name: feishuBotGroups.chat_name,
+      })
+      .from(feishuBotGroups)
+      .where(eq(feishuBotGroups.creator_open_id, creatorOpenId))
+      .all()
+      .filter((row) => row.chat_id === query || row.chat_name === query);
+  }
+
+  /** Remove a bot-group record. Call after a successful `dismissChat`. */
+  deleteBotGroupRecord(chatId: string): void {
+    this._db
+      .delete(feishuBotGroups)
+      .where(eq(feishuBotGroups.chat_id, chatId))
+      .run();
+  }
+
+  /**
+   * Add one or more users to the runtime whitelist and persist the change to
+   * `config.yaml`. Returns the open_ids that were actually new (not already
+   * in the set) so callers can report a precise count back to the user.
+   *
+   * Mutates the channel's in-memory set immediately — new entries take effect
+   * on the very next inbound message without a restart. Persistence keeps
+   * the change across restarts; we re-use Bun's YAML parser/stringifier so
+   * the file stays round-trippable.
+   *
+   * `senderOpenId` is required so we can auto-seed the operator into the
+   * whitelist when transitioning from the implicit "everyone allowed" state
+   * (no whitelist configured) to an explicit list. Without this seed, a
+   * freshly-initialized whitelist would exclude the very user who just ran
+   * `/allow`, locking them out of their own bot on the next message.
+   */
+  async addToWhitelist(
+    openIds: string[],
+    senderOpenId: string,
+  ): Promise<string[]> {
+    const hadWhitelist = !!this._allowedUserOpenIds;
+    if (!this._allowedUserOpenIds) {
+      this._allowedUserOpenIds = new Set<string>();
+    }
+    const added: string[] = [];
+    // Bootstrap guard: the previous state allowed everyone implicitly.
+    // Preserve access for the operator when we materialize that into an
+    // explicit list.
+    if (!hadWhitelist && !this._allowedUserOpenIds.has(senderOpenId)) {
+      this._allowedUserOpenIds.add(senderOpenId);
+      added.push(senderOpenId);
+    }
+    for (const openId of openIds) {
+      if (!this._allowedUserOpenIds.has(openId)) {
+        this._allowedUserOpenIds.add(openId);
+        added.push(openId);
+      }
+    }
+    if (added.length === 0) return added;
+    try {
+      await this._persistWhitelistToConfig();
+    } catch (err) {
+      this._logger.error(
+        { err, channel_id: this.id, added },
+        "failed to persist whitelist addition; in-memory set was still updated",
+      );
+      throw err;
+    }
+    return added;
+  }
+
+  private async _persistWhitelistToConfig(): Promise<void> {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const { config: cfgModule } = await import("@/shared");
+    const configPath = path.join(cfgModule.paths.home, "config.yaml");
+    const raw = await fs.readFile(configPath, "utf-8");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun.YAML types are not in @types yet
+    const parsed = (Bun as any).YAML.parse(raw) as {
+      messaging?: {
+        channels?: Array<{
+          id: string;
+          params?: Record<string, unknown>;
+        }>;
+      };
+    };
+    const channel = parsed.messaging?.channels?.find((c) => c.id === this.id);
+    if (!channel) {
+      throw new Error(
+        `channel \`${this.id}\` not found in config.yaml — whitelist write aborted`,
+      );
+    }
+    if (!channel.params) channel.params = {};
+    channel.params.allowed_user_ids = Array.from(
+      this._allowedUserOpenIds ?? [],
+    );
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun.YAML types are not in @types yet
+    const serialized = (Bun as any).YAML.stringify(parsed);
+    await fs.writeFile(configPath, serialized, "utf-8");
+  }
+
+  /**
+   * Exchange app credentials for a tenant access token. Used for REST calls
+   * that the node-sdk doesn't expose directly (bot info, email→id lookup).
+   */
+  private async _fetchTenantAccessToken(): Promise<string> {
+    const res = await fetch(
+      "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+        body: JSON.stringify({
+          app_id: this.config.appId,
+          app_secret: this.config.appSecret,
+        }),
+      },
+    );
+    const json = (await res.json()) as {
+      code: number;
+      msg: string;
+      tenant_access_token?: string;
+    };
+    if (json.code !== 0 || !json.tenant_access_token) {
+      throw new Error(
+        `Failed to obtain tenant_access_token: ${json.code} ${json.msg}`,
+      );
+    }
+    return json.tenant_access_token;
+  }
+
+  /**
+   * Fetch the bot's own open_id via `/bot/v3/info`. Requires the bot app to
+   * have "Get bot info" permission. Throws on failure — we'd rather fail loud
+   * than silently accept every message when the user asked for mention-only.
+   */
+  private async _fetchBotOpenId(tenantToken: string): Promise<string> {
+    const res = await fetch("https://open.feishu.cn/open-apis/bot/v3/info", {
+      method: "GET",
+      headers: { Authorization: `Bearer ${tenantToken}` },
+    });
+    const json = (await res.json()) as {
+      code: number;
+      msg: string;
+      bot?: { open_id?: string };
+    };
+    if (json.code !== 0 || !json.bot?.open_id) {
+      throw new Error(`Failed to fetch bot info: ${json.code} ${json.msg}`);
+    }
+    return json.bot.open_id;
+  }
+
+  /**
+   * Resolve emails to open_ids via `/contact/v3/users/batch_get_id`. Requires
+   * the bot app to have "Get user ID by mobile/email" permission. Emails that
+   * don't map to a user are omitted from the returned map (the caller logs
+   * unresolved entries). Batches of 50 per the API limit.
+   */
+  private async _resolveEmailsToOpenIds(
+    emails: string[],
+    tenantToken: string,
+  ): Promise<Map<string, string>> {
+    const result = new Map<string, string>();
+    for (let i = 0; i < emails.length; i += 50) {
+      const batch = emails.slice(i, i + 50);
+      const res = await fetch(
+        "https://open.feishu.cn/open-apis/contact/v3/users/batch_get_id?user_id_type=open_id",
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${tenantToken}`,
+            "Content-Type": "application/json; charset=utf-8",
+          },
+          body: JSON.stringify({ emails: batch, mobiles: [] }),
+        },
+      );
+      const json = (await res.json()) as {
+        code: number;
+        msg: string;
+        data?: {
+          user_list?: Array<{ email?: string; user_id?: string }>;
+        };
+      };
+      if (json.code !== 0) {
+        throw new Error(
+          `Failed to resolve emails (${batch.length}): ${json.code} ${json.msg}`,
+        );
+      }
+      for (const entry of json.data?.user_list ?? []) {
+        if (entry.email && entry.user_id) {
+          result.set(entry.email, entry.user_id);
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Reply to a message. Defaults to opening a new Feishu topic
+   * (`reply_in_thread: true`) because most replies are session-scoped
+   * assistant output. Pass `replyInThread: false` for one-shot replies (slash
+   * commands, quick error messages) that should render inline instead.
+   *
+   * When `replyInThread` is false, the thread→session mapping is skipped —
+   * there's no new thread to map, and the reply doesn't belong to any
+   * session anyway.
+   */
   async replyMessage(
     messageId: string,
     message: Omit<AssistantMessage, "id">,
-    { streaming = true }: { streaming?: boolean } = {},
+    {
+      streaming = true,
+      replyInThread = true,
+    }: { streaming?: boolean; replyInThread?: boolean } = {},
   ): Promise<AssistantMessage> {
-    const { firstMessageContent, remainingChunks } = this._prepareMessageContent(
-      message.content,
-      streaming,
-    );
-
-    const card = await renderMessageCard(firstMessageContent, {
-      streaming,
-      uploadImage: this.uploadImage.bind(this),
-    });
+    const { primaryContent, markdownContinuations } =
+      this._prepareCardPayload(message.content, streaming);
     if (!streaming) {
       this._logOutboundMessage(message.session_id, message.content);
     }
+
+    const baseDir = this._resolveWorkspaceBaseDir(message.session_id);
+    const primaryCard = await renderMessageCard(primaryContent, {
+      streaming,
+      uploadImage: (p) => this.uploadImage(p, baseDir),
+    });
     const { data: replyMessage } = await this._client.im.message.reply({
-      path: {
-        message_id: messageId,
-      },
+      path: { message_id: messageId },
       data: {
         msg_type: "interactive",
-        content: JSON.stringify(card),
-        reply_in_thread: true,
+        content: JSON.stringify(primaryCard),
+        reply_in_thread: replyInThread,
       },
     });
-    if (!replyMessage) {
+    if (!replyMessage?.message_id) {
       throw new Error("Failed to reply message");
     }
+    const primaryId = replyMessage.message_id;
 
-    const { thread_id: threadId } = replyMessage;
-    const sessionId = message.session_id;
-    this._mapThreadToSession(threadId!, sessionId);
+    if (replyInThread && replyMessage.thread_id) {
+      this._mapThreadToSession(replyMessage.thread_id, message.session_id);
+    }
+
+    if (streaming) {
+      this._cardStartedAt.set(primaryId, Date.now());
+    }
 
-    await this._sendRemainingChunks(replyMessage.message_id!, remainingChunks);
+    if (!streaming && markdownContinuations.length > 0) {
+      await this._postMarkdownContinuations(
+        primaryId,
+        markdownContinuations,
+        replyInThread,
+        message.session_id,
+      );
+      this._finalizedPrimaries.add(primaryId);
+    }
 
     const assistantMessage = message as AssistantMessage;
-    assistantMessage.id = replyMessage.message_id!;
+    assistantMessage.id = primaryId;
 
     if (!streaming) {
-      const lastText = message.content.filter((c) => c.type === "text").pop();
-      if (lastText?.type === "text") {
-        await this._sendLocalFileAttachments(
-          assistantMessage.id,
-          lastText.text,
-        );
-      }
+      await this._sendFileAttachmentsForFinalText(
+        assistantMessage.id,
+        message.content,
+        message.session_id,
+      );
     }
-
     return assistantMessage;
   }
 
   async postMessage(
     message: Omit<AssistantMessage, "id">,
   ): Promise<AssistantMessage> {
-    const { firstMessageContent, remainingChunks } = this._prepareMessageContent(
-      message.content,
-      false,
-    );
+    const { primaryContent, markdownContinuations } =
+      this._prepareCardPayload(message.content, false);
+    this._logOutboundMessage(message.session_id, message.content);
 
-    const card = await renderMessageCard(firstMessageContent, {
+    const baseDir = this._resolveWorkspaceBaseDir(message.session_id);
+    const primaryCard = await renderMessageCard(primaryContent, {
       streaming: false,
-      uploadImage: this.uploadImage.bind(this),
+      uploadImage: (p) => this.uploadImage(p, baseDir),
     });
-    this._logOutboundMessage(message.session_id, message.content);
     const { data } = await this._client.im.message.create({
-      params: {
-        receive_id_type: "chat_id",
-      },
+      params: { receive_id_type: "chat_id" },
       data: {
         receive_id: this.config.chatId,
         msg_type: "interactive",
-        content: JSON.stringify(card),
+        content: JSON.stringify(primaryCard),
       },
     });
-    if (!data) {
+    if (!data?.message_id) {
       throw new Error("Failed to post message");
     }
-    const { message_id: messageId } = data;
-    const assistantMessage = message as AssistantMessage;
-    assistantMessage.id = messageId!;
+    const primaryId = data.message_id;
 
-    await this._sendRemainingChunks(assistantMessage.id, remainingChunks);
-
-    const lastText = message.content.filter((c) => c.type === "text").pop();
-    if (lastText?.type === "text") {
-      await this._sendLocalFileAttachments(assistantMessage.id, lastText.text);
+    if (markdownContinuations.length > 0) {
+      await this._postMarkdownContinuations(
+        primaryId,
+        markdownContinuations,
+        /* replyInThread */ true,
+        message.session_id,
+      );
     }
+    this._finalizedPrimaries.add(primaryId);
+
+    const assistantMessage = message as AssistantMessage;
+    assistantMessage.id = primaryId;
+
+    await this._sendFileAttachmentsForFinalText(
+      assistantMessage.id,
+      message.content,
+      message.session_id,
+    );
 
     const emojis = [
       "思考中",
@@ -200,9 +722,7 @@ export class FeishuMessageChannel
       "挥手",
     ];
     const { data: replyData } = await this._client.im.message.reply({
-      path: {
-        message_id: assistantMessage.id,
-      },
+      path: { message_id: assistantMessage.id },
       data: {
         content: JSON.stringify({
           type: "text",
@@ -212,10 +732,8 @@ export class FeishuMessageChannel
         reply_in_thread: true,
       },
     });
-    if (replyData) {
-      const { thread_id: threadId } = replyData;
-      const sessionId = message.session_id;
-      this._mapThreadToSession(threadId!, sessionId);
+    if (replyData?.thread_id) {
+      this._mapThreadToSession(replyData.thread_id, message.session_id);
     }
     return assistantMessage;
   }
@@ -223,32 +741,37 @@ export class FeishuMessageChannel
   /** Update the content of an existing Feishu message. */
   async updateMessageContent(
     message: AssistantMessage,
-    { streaming = true }: { streaming?: boolean } = {},
+    {
+      streaming = true,
+      footer,
+    }: { streaming?: boolean; footer?: CardFooterStats } = {},
   ): Promise<void> {
     if (this._failedCardUpdateMessages.has(message.id)) {
       return;
     }
 
-    const { firstMessageContent, remainingChunks } = this._prepareMessageContent(
-      message.content,
-      streaming,
-    );
-
-    const card = await renderMessageCard(firstMessageContent, {
-      streaming,
-      uploadImage: this.uploadImage.bind(this),
-    });
+    const { primaryContent, markdownContinuations } =
+      this._prepareCardPayload(message.content, streaming);
     if (!streaming) {
       this._logOutboundMessage(message.session_id, message.content);
     }
+
+    const startedAt = this._cardStartedAt.get(message.id);
+    const elapsedMs =
+      !streaming && typeof startedAt === "number"
+        ? Date.now() - startedAt
+        : undefined;
+    const baseDir = this._resolveWorkspaceBaseDir(message.session_id);
+    const card = await renderMessageCard(primaryContent, {
+      streaming,
+      uploadImage: (p) => this.uploadImage(p, baseDir),
+      elapsedMs,
+      footer,
+    });
     try {
       await this._client.im.message.patch({
-        path: {
-          message_id: message.id,
-        },
-        data: {
-          content: JSON.stringify(card),
-        },
+        path: { message_id: message.id },
+        data: { content: JSON.stringify(card) },
       });
     } catch (err) {
       if (_isFeishuBadRequestError(err)) {
@@ -262,24 +785,70 @@ export class FeishuMessageChannel
       }
       throw err;
     }
+    if (!streaming) {
+      this._cardStartedAt.delete(message.id);
+    }
 
-    await this._sendRemainingChunks(message.id, remainingChunks);
-
+    // Markdown continuations are only meaningful once the run is final —
+    // during streaming the "final text" hasn't stabilized yet. Post them
+    // exactly once per primary message.
+    if (
+      !streaming &&
+      markdownContinuations.length > 0 &&
+      !this._finalizedPrimaries.has(message.id)
+    ) {
+      await this._postMarkdownContinuations(
+        message.id,
+        markdownContinuations,
+        /* replyInThread */ true,
+        message.session_id,
+      );
+    }
     if (!streaming) {
-      const lastText = message.content.filter((c) => c.type === "text").pop();
-      if (lastText?.type === "text") {
-        await this._sendLocalFileAttachments(message.id, lastText.text);
-      }
+      this._finalizedPrimaries.add(message.id);
+      await this._sendFileAttachmentsForFinalText(
+        message.id,
+        message.content,
+        message.session_id,
+      );
     }
   }
 
+  /**
+   * Base directory for resolving agent-generated relative paths (markdown
+   * image/file links). The agent ran with its cwd set to the session's
+   * workspace, so its relative paths are relative to *that* directory — not
+   * the global `$AGENTARA_HOME`, and not necessarily `this.config.chatId`'s
+   * workspace (a single channel serves replies for many chats).
+   *
+   * Resolution order:
+   * 1. The owning session's recorded cwd (most precise — it's exactly where
+   *    the agent wrote the file).
+   * 2. The channel's configured chat workspace (legacy fallback).
+   * 3. Agentara home (tests / unwired callers).
+   *
+   * @param sessionId - Session that produced the outbound message, when known.
+   */
+  private _resolveWorkspaceBaseDir(sessionId?: string): string {
+    return (
+      (sessionId ? this._resolveSessionCwd?.(sessionId) : undefined) ??
+      this._resolveWorkspaceCwd?.(this.config.chatId) ??
+      config.paths.home
+    );
+  }
+
   /**
    * Uploads an image to Feishu. Returns the key of the uploaded image.
    * @param path - The path to the image to upload.
+   * @param baseDir - Directory to resolve a relative `path` against. Defaults
+   *   to the channel's configured-chat workspace; callers that know the
+   *   owning session should pass that session's cwd.
    * @returns The key of the uploaded image.
    */
-  async uploadImage(path: string): Promise<string> {
-    const absPath = nodePath.join(config.paths.home, path);
+  async uploadImage(path: string, baseDir?: string): Promise<string> {
+    const absPath = nodePath.isAbsolute(path)
+      ? path
+      : nodePath.join(baseDir ?? this._resolveWorkspaceBaseDir(), path);
     const file = fs.readFileSync(absPath);
     this._logger.info(`Uploading image ${absPath}`);
     const res = await this._client.im.v1.image.create({
@@ -300,11 +869,17 @@ export class FeishuMessageChannel
 
   /**
    * Uploads a file to Feishu. Returns the key of the uploaded file.
-   * @param filePath - The path to the file relative to the home directory.
+   * @param filePath - Absolute path, or a path relative to `baseDir`
+   *   (agent-generated markdown links).
+   * @param baseDir - Directory to resolve a relative `filePath` against.
+   *   Defaults to the channel's configured-chat workspace; callers that know
+   *   the owning session should pass that session's cwd.
    * @returns The key of the uploaded file.
    */
-  async uploadFile(filePath: string): Promise<string> {
-    const absPath = nodePath.join(config.paths.home, filePath);
+  async uploadFile(filePath: string, baseDir?: string): Promise<string> {
+    const absPath = nodePath.isAbsolute(filePath)
+      ? filePath
+      : nodePath.join(baseDir ?? this._resolveWorkspaceBaseDir(), filePath);
     const file = fs.createReadStream(absPath);
     const fileName = nodePath.basename(absPath);
     const ext = nodePath.extname(absPath).slice(1).toLowerCase();
@@ -345,14 +920,20 @@ export class FeishuMessageChannel
    * Downloads an image or a file from a message.
    * @param messageId - The ID of the message to download the resource from.
    * @param file_key - The key of the file to download.
-   * @param file_name - The name of the file to download. If not provided, the file name will be inferred from the file key.
-   * @returns The path to the downloaded file.
+   * @param options.file_name - Optional file name; inferred from metadata
+   *   when omitted.
+   * @param options.targetDir - Absolute root directory for the download.
+   *   Defaults to the global `$AGENTARA_HOME/workspace/uploads` when
+   *   unspecified. Channel callers pass the per-chat workspace cwd so
+   *   uploads land inside the workspace that triggered them.
+   * @returns Absolute path to the downloaded file.
    */
   async downloadMessageResource(
     messageId: string,
     file_key: string,
-    file_name?: string,
+    options?: { file_name?: string; targetDir?: string },
   ): Promise<string> {
+    const { file_name, targetDir } = options ?? {};
     const { writeFile, headers } = await this._client.im.v1.messageResource.get(
       {
         path: {
@@ -371,7 +952,10 @@ export class FeishuMessageChannel
       Mime: string;
     };
     const isImage = metadata.Mime.startsWith("image/");
-    let dir = config.paths.uploads;
+    const root = targetDir
+      ? nodePath.join(targetDir, "uploads")
+      : config.paths.uploads;
+    let dir = root;
     if (isImage) {
       dir = nodePath.join(dir, "images");
     }
@@ -401,82 +985,113 @@ export class FeishuMessageChannel
       filename += `-${i}`;
     }
     filename += extname;
-    await writeFile(nodePath.join(dir, filename));
-    return nodePath.relative(config.paths.home, nodePath.join(dir, filename));
+    const absPath = nodePath.join(dir, filename);
+    await writeFile(absPath);
+    // Return an absolute path. Claude Code's cwd is the per-group
+    // workspace dir (`$AGENTARA_HOME/workspaces/<id>/`), not
+    // `$AGENTARA_HOME`, so a path relative to HOME would fail to
+    // resolve inside the agent's read tools.
+    return absPath;
   }
 
   /**
-   * Prepare message content for sending, splitting if necessary due to table limits.
-   * @param content - Original message content.
-   * @param streaming - Whether the message is being streamed (skip splitting if true).
-   * @returns First chunk content and remaining chunks to send as follow-ups.
+   * Split an assistant message's final text (if any) into the part that
+   * fits on the primary card plus a list of overflow markdown strings
+   * that will each become a text-only continuation card.
+   *
+   * Tool steps never spill — the renderer truncates the step panel to a
+   * windowed view when there are too many. Only the final answer gets
+   * spilled, and only when it's either table-dense (Feishu caps tables
+   * per card) or byte-heavy (Feishu caps card body size). During
+   * streaming we skip the spill entirely: the "final text" hasn't
+   * stabilized and any interim text is ephemeral.
    */
-  private _prepareMessageContent(
+  private _prepareCardPayload(
     content: AssistantMessage["content"],
     streaming: boolean,
   ): {
-    firstMessageContent: AssistantMessage["content"];
-    remainingChunks: string[];
+    primaryContent: AssistantMessage["content"];
+    markdownContinuations: string[];
   } {
-    const lastTextContent = content.findLast((c) => c.type === "text");
-    const markdownChunks = lastTextContent
-      ? splitMarkdownByTables(lastTextContent.text)
-      : [];
-    const needsSplit = !streaming && markdownChunks.length > 1;
-
-    const firstMessageContent = needsSplit
-      ? (content.map((c) =>
-          c.type === "text" ? { ...c, text: markdownChunks[0] } : c,
-        ) as AssistantMessage["content"])
-      : content;
-
-    const remainingChunks = needsSplit ? markdownChunks.slice(1) : [];
-
-    return { firstMessageContent, remainingChunks };
+    if (streaming) {
+      return { primaryContent: content, markdownContinuations: [] };
+    }
+    const lastTextIdx = content.findLastIndex((c) => c.type === "text");
+    if (lastTextIdx === -1) {
+      return { primaryContent: content, markdownContinuations: [] };
+    }
+    const lastText = content[lastTextIdx]!;
+    if (lastText.type !== "text") {
+      return { primaryContent: content, markdownContinuations: [] };
+    }
+    const markdownChunks = splitMarkdownForCards(lastText.text);
+    if (markdownChunks.length <= 1) {
+      return { primaryContent: content, markdownContinuations: [] };
+    }
+    const rewritten = [...content];
+    rewritten[lastTextIdx] = { ...lastText, text: markdownChunks[0]! };
+    return {
+      primaryContent: rewritten as AssistantMessage["content"],
+      markdownContinuations: markdownChunks.slice(1),
+    };
   }
 
   /**
-   * Send remaining markdown chunks as follow-up reply messages.
-   * @param messageId - The message ID to reply to.
-   * @param chunks - Array of markdown strings to send.
+   * Post the overflow markdown chunks as text-only reply cards
+   * underneath the primary. Called at most once per primary, at the
+   * moment we finalize the message.
    */
-  private async _sendRemainingChunks(
-    messageId: string,
-    chunks: string[],
+  private async _postMarkdownContinuations(
+    primaryId: string,
+    markdownChunks: string[],
+    replyInThread: boolean,
+    sessionId?: string,
   ): Promise<void> {
-    for (const chunkText of chunks) {
-      const chunkCard = await renderMessageCard(
-        [{ type: "text", text: chunkText }],
-        {
-          streaming: false,
-          uploadImage: this.uploadImage.bind(this),
-        },
-      );
+    const baseDir = this._resolveWorkspaceBaseDir(sessionId);
+    for (const text of markdownChunks) {
+      const card = await renderMessageCard([{ type: "text", text }], {
+        streaming: false,
+        uploadImage: (p) => this.uploadImage(p, baseDir),
+      });
       await this._client.im.message.reply({
-        path: {
-          message_id: messageId,
-        },
+        path: { message_id: primaryId },
         data: {
           msg_type: "interactive",
-          content: JSON.stringify(chunkCard),
-          reply_in_thread: true,
+          content: JSON.stringify(card),
+          reply_in_thread: replyInThread,
         },
       });
     }
   }
 
-  /** Extract local file paths from markdown link syntax [text](path) in text. */
-  private _extractLocalFilePaths(text: string): string[] {
+  /** Send file attachments referenced in the final text block, if any. */
+  private async _sendFileAttachmentsForFinalText(
+    messageId: string,
+    content: AssistantMessage["content"],
+    sessionId?: string,
+  ): Promise<void> {
+    const lastText = content.filter((c) => c.type === "text").pop();
+    if (lastText?.type === "text") {
+      await this._sendLocalFileAttachments(messageId, lastText.text, sessionId);
+    }
+  }
+
+  /**
+   * Extract local file paths from markdown link syntax [text](path) in text.
+   * Relative paths are resolved against the owning session's workspace cwd.
+   */
+  private _extractLocalFilePaths(text: string, sessionId?: string): string[] {
     const linkRegex = /(?<!!)\[.*?\]\(([^)]+)\)/g;
+    const baseDir = this._resolveWorkspaceBaseDir(sessionId);
     const paths: string[] = [];
     let match: RegExpExecArray | null;
     while ((match = linkRegex.exec(text)) !== null) {
       const filePath = match[1];
-      if (
-        filePath &&
-        !filePath.includes("://") &&
-        fs.existsSync(nodePath.join(config.paths.home, filePath))
-      ) {
+      if (!filePath || filePath.includes("://")) continue;
+      const absPath = nodePath.isAbsolute(filePath)
+        ? filePath
+        : nodePath.join(baseDir, filePath);
+      if (fs.existsSync(absPath)) {
         paths.push(filePath);
       }
     }
@@ -487,14 +1102,16 @@ export class FeishuMessageChannel
   private async _sendLocalFileAttachments(
     messageId: string,
     text: string,
+    sessionId?: string,
   ): Promise<void> {
-    const filePaths = this._extractLocalFilePaths(text);
+    const filePaths = this._extractLocalFilePaths(text, sessionId);
+    const baseDir = this._resolveWorkspaceBaseDir(sessionId);
     const seen = new Set<string>();
     for (const filePath of filePaths) {
       if (seen.has(filePath)) continue;
       seen.add(filePath);
       try {
-        const fileKey = await this.uploadFile(filePath);
+        const fileKey = await this.uploadFile(filePath, baseDir);
         await this._client.im.message.reply({
           path: { message_id: messageId },
           data: {
@@ -513,6 +1130,37 @@ export class FeishuMessageChannel
     }
   }
 
+  /**
+   * Post a short plain-text reply when an inbound message is dropped by a
+   * gate (whitelist / mention enforcement). Only used for messages whose
+   * intent is clearly directed at the bot — otherwise the bot would spam
+   * rejection replies at every unrelated group message.
+   */
+  private async _replyRejection(
+    messageId: string,
+    reason: "whitelist" | "mention",
+  ): Promise<void> {
+    const text =
+      reason === "whitelist"
+        ? "❌ 未授权：你不在本机器人白名单。请让已授权的成员用 `/allow @你` 把你加入。"
+        : "❌ 本群需要 @ 机器人才能触发对话（`/` 斜杠命令除外）。";
+    try {
+      await this._client.im.message.reply({
+        path: { message_id: messageId },
+        data: {
+          msg_type: "text",
+          content: JSON.stringify({ text }),
+          reply_in_thread: false,
+        },
+      });
+    } catch (err) {
+      this._logger.warn(
+        { err, message_id: messageId, reason },
+        "failed to send rejection reply",
+      );
+    }
+  }
+
   private async _replyUpdateFailureMessage(messageId: string): Promise<void> {
     try {
       await this._client.im.message.reply({
@@ -544,22 +1192,164 @@ export class FeishuMessageChannel
     this._logger.info([sessionId, finalText], "Final Feishu outbound content");
   }
 
-  private _handleMessageReceive = async ({
-    message: receivedMessage,
-  }: MessageReceiveEventData) => {
-    const { message_id: messageId, thread_id: threadId } = receivedMessage;
-    const session_id = this._resolveSessionId(threadId);
+  private _handleMessageReceive = async (
+    eventData: MessageReceiveEventData,
+  ) => {
+    const { sender, message: receivedMessage } = eventData;
+    const {
+      message_id: messageId,
+      thread_id: threadId,
+      chat_id: chatId,
+      chat_type: chatType,
+      message_type: messageType,
+      parent_id: parentId,
+      mentions,
+    } = receivedMessage;
+    const senderOpenId = sender?.sender_id?.open_id;
+
+    const isAllowedSender =
+      !this._allowedUserOpenIds ||
+      (senderOpenId != null && this._allowedUserOpenIds.has(senderOpenId));
+
+    // Slash commands (e.g. `/setup`, `/bind`) intentionally bypass the
+    // @-mention requirement — operators should be able to run them with a
+    // single keystroke in the chat bar. The sender whitelist still applies.
+    const isSlashCommand = _peekSlashCommand(
+      messageType,
+      receivedMessage.content,
+    );
+    // Messages inside a thread the bot has already engaged in still require
+    // an @-mention by default — otherwise casual in-thread chatter between
+    // humans would make the bot reply to every line. Operators can flip the
+    // thread into "auto-respond" mode via `/unmute`, which is what this flag
+    // reflects. `/mute` restores the default.
+    const isThreadAutoRespond = this._isThreadAutoRespond(threadId);
+    const mentionEnforced =
+      this._requireMention &&
+      chatType === "group" &&
+      !isSlashCommand &&
+      !isThreadAutoRespond;
+    const isBotMentioned =
+      !!this._botOpenId &&
+      !!mentions?.some((m) => m.id?.open_id === this._botOpenId);
+    const mentionOk = !mentionEnforced || isBotMentioned;
+
+    this._logger.info(
+      {
+        message_id: messageId,
+        chat_id: chatId,
+        chat_type: chatType,
+        message_type: messageType,
+        sender_open_id: senderOpenId,
+        bot_mentioned: isBotMentioned,
+        slash_command: isSlashCommand,
+        thread_auto_respond: isThreadAutoRespond,
+        passed: isAllowedSender && mentionOk,
+      },
+      "inbound message",
+    );
+
+    // A message is "directed at the bot" if the intent is unambiguous —
+    // slash command, explicit @-mention, inside an auto-respond thread, or
+    // a p2p chat. We only surface rejection replies for these; casual
+    // non-whitelisted chatter inside a muted bot-thread is silently dropped
+    // so the bot doesn't interrupt human side-discussions.
+    const isIntendedForBot =
+      isSlashCommand ||
+      isBotMentioned ||
+      isThreadAutoRespond ||
+      chatType === "p2p";
+
+    if (!isAllowedSender) {
+      this._logger.info(
+        { message_id: messageId, sender_open_id: senderOpenId },
+        "dropping inbound: sender not in whitelist",
+      );
+      if (isIntendedForBot) {
+        await this._replyRejection(messageId, "whitelist");
+      }
+      return;
+    }
+    if (!mentionOk) {
+      this._logger.info(
+        { message_id: messageId, chat_id: chatId },
+        "dropping inbound: bot not @mentioned in group chat",
+      );
+      // `mentionEnforced` already excludes slash_command / in_bot_thread, so
+      // reaching here means the message has no directed signal. Stay silent.
+      return;
+    }
+
+    const session_id = this._resolveSessionId(chatId, threadId);
+    // Normalize Feishu's chat_type into the shared enum so command handlers
+    // can gate on group-vs-P2P without reaching back into provider details.
+    // Feishu emits `"p2p"` (not `"single"`) for 1:1 chats — accept both to be
+    // robust against SDK version drift.
+    const normalizedChatType: "group" | "single" | undefined =
+      chatType === "group"
+        ? "group"
+        : chatType === "p2p" || chatType === "single"
+          ? "single"
+          : undefined;
+    // Propagate the raw Feishu mentions into a provider-agnostic list so
+    // downstream command handlers (`/group`, `/allow`) can resolve the
+    // `@_user_N` placeholders that appear in the text content.
+    const normalizedMentions: Array<{
+      key: string;
+      open_id: string;
+      name?: string;
+    }> = [];
+    for (const m of mentions ?? []) {
+      const openId = m.id?.open_id;
+      if (!openId || !m.key) continue;
+      normalizedMentions.push({
+        key: m.key,
+        open_id: openId,
+        name: m.name,
+      });
+    }
+    // Per-chat download root so files land inside the workspace that
+    // actually triggered them. Falls back to the global uploads dir when
+    // the kernel didn't wire a resolver (tests, legacy callers).
+    const targetDir = this._resolveWorkspaceCwd
+      ? this._resolveWorkspaceCwd(chatId)
+      : undefined;
+
+    const content: UserMessage["content"] = [];
+    // When the user reply-quoted an earlier message AND the new message
+    // is directed at the bot, surface the quoted context so Claude can
+    // see what they're actually pointing at. Skip when it's just an
+    // in-thread reply with no explicit quote signal to the bot. Slash
+    // commands are gateway-level and operate on bot state — prepending
+    // the quoted block would corrupt the leading `/…` and prevent the
+    // kernel from routing it.
+    if (parentId && isIntendedForBot && !isSlashCommand) {
+      const info = await this._fetchQuotedMessage(parentId, targetDir);
+      content.push({
+        type: "text",
+        text: _formatQuotedBlock(info, parentId),
+      });
+    }
+    content.push(
+      await this._parseMessageContent(
+        messageId,
+        receivedMessage.message_type,
+        receivedMessage.content,
+        targetDir,
+      ),
+    );
     const userMessage: UserMessage = {
       id: messageId,
       session_id,
       role: "user",
-      content: [
-        await this._parseMessageContent(
-          messageId,
-          receivedMessage.message_type,
-          receivedMessage.content,
-        ),
-      ],
+      channel_id: this.id,
+      chat_id: chatId,
+      chat_type: normalizedChatType,
+      thread_id: threadId,
+      sender_open_id: senderOpenId,
+      mentions:
+        normalizedMentions.length > 0 ? normalizedMentions : undefined,
+      content,
     };
     this.emit("message:inbound", userMessage);
   };
@@ -575,45 +1365,363 @@ export class FeishuMessageChannel
     this.emit("message:recalled", data.message_id, this.id);
   };
 
-  private _threadIdToSessionId = new Map<string, string>();
+  /**
+   * Handle a `card.action.trigger` event delivered via the WS event stream.
+   * Normalizes the provider-specific shape into `CardActionPayload` and emits
+   * `card:action`; the kernel dispatches by `action_name`.
+   */
+  private _handleCardAction = async (data: {
+    operator?: { open_id?: string; tenant_key?: string };
+    action?: {
+      value?: Record<string, unknown>;
+      form_value?: Record<string, unknown>;
+      tag?: string;
+      name?: string;
+    };
+    context?: { open_message_id?: string; open_chat_id?: string };
+  }) => {
+    const messageId = data.context?.open_message_id;
+    const operatorOpenId = data.operator?.open_id;
+    if (!messageId || !operatorOpenId) {
+      this._logger.warn(
+        { data },
+        "ignoring card.action.trigger with missing message_id/operator",
+      );
+      return;
+    }
+    const value = data.action?.value ?? {};
+    // `action.value.action` is set for callback buttons (`behaviors[].value`).
+    // For form_submit buttons we don't attach behaviors, so fall back to the
+    // submit button's `name`, which Feishu echoes at `action.name`. That makes
+    // the submit-button name the de-facto action discriminator for forms.
+    const actionName =
+      typeof value.action === "string"
+        ? value.action
+        : typeof data.action?.name === "string"
+          ? data.action.name
+          : "";
+    const payload: CardActionPayload = {
+      message_id: messageId,
+      channel_id: this.id,
+      chat_id: data.context?.open_chat_id,
+      operator_open_id: operatorOpenId,
+      action_name: actionName,
+      value,
+      form_value: data.action?.form_value ?? {},
+    };
+    this._logger.info(
+      {
+        message_id: messageId,
+        action_name: actionName,
+        operator_open_id: operatorOpenId,
+        form_value: data.action?.form_value,
+        raw_value: value,
+      },
+      "card action",
+    );
+    // Defer downstream dispatch to a later macrotask so the synchronous ack
+    // below reaches Feishu first. `emit` runs listeners synchronously, and a
+    // handler may do blocking sync work (e.g. workspace deletion calls
+    // `rmSync` on a directory tree), which would otherwise stall the event
+    // loop before this function can return its ack — causing the card button
+    // to hit Feishu's callback timeout while the work is still running.
+    setTimeout(() => {
+      this.emit("card:action", payload);
+    }, 0);
+    // Acknowledge the action back to Feishu via the WS response (the SDK
+    // base64-encodes this as respPayload.data). Without an ack, the card UI
+    // can surface a generic failure toast while the real work happens
+    // asynchronously. Handlers downstream update the card in-place via
+    // `updateRawCard` when done.
+    return {
+      toast: { type: "info", content: "已收到，正在处理…" },
+    };
+  };
+
+  private _threadState = new Map<
+    string,
+    { session_id: string; auto_respond: boolean }
+  >();
+
+  /**
+   * Returns true when the thread is explicitly opted into "auto respond"
+   * mode, i.e. the operator ran `/unmute` in it. Default for every
+   * bot-participated thread is false — group messages must still @-mention
+   * the bot even inside a bot-owned topic. Cheap: in-memory cache first,
+   * then indexed single-row lookup on `feishu_threads`.
+   */
+  private _isThreadAutoRespond(threadId: string | undefined): boolean {
+    if (!threadId) return false;
+    const cached = this._threadState.get(threadId);
+    if (cached) return cached.auto_respond;
+    const row = this._db
+      .select({
+        session_id: feishuThreads.session_id,
+        auto_respond: feishuThreads.auto_respond,
+      })
+      .from(feishuThreads)
+      .where(eq(feishuThreads.thread_id, threadId))
+      .get();
+    if (row) {
+      const state = {
+        session_id: row.session_id,
+        auto_respond: row.auto_respond === 1,
+      };
+      this._threadState.set(threadId, state);
+      return state.auto_respond;
+    }
+    return false;
+  }
+
+  /**
+   * Public lookup of a thread's mapping row: the bound session_id and the
+   * auto-respond flag. Returns undefined when neither the in-memory cache
+   * nor the `feishu_threads` table knows about the thread (e.g. the topic
+   * was just opened and the bot hasn't replied into it yet).
+   *
+   * Used by `/topic` to surface "where am I" info without leaking the
+   * private DB shape.
+   */
+  getThreadInfo(
+    threadId: string,
+  ): { session_id: string; auto_respond: boolean } | undefined {
+    const cached = this._threadState.get(threadId);
+    if (cached) return { ...cached };
+    const row = this._db
+      .select({
+        session_id: feishuThreads.session_id,
+        auto_respond: feishuThreads.auto_respond,
+      })
+      .from(feishuThreads)
+      .where(eq(feishuThreads.thread_id, threadId))
+      .get();
+    if (!row) return undefined;
+    const state = {
+      session_id: row.session_id,
+      auto_respond: row.auto_respond === 1,
+    };
+    this._threadState.set(threadId, state);
+    return { ...state };
+  }
+
+  /**
+   * Flip the auto-respond flag on a thread. Persists to DB and updates the
+   * in-memory cache so the change takes effect on the very next inbound
+   * message. Creates the row if missing, though typically the thread has
+   * already been mapped by {@link _mapThreadToSession} via an earlier bot
+   * reply. Returns the resolved session id for the thread.
+   */
+  setThreadAutoRespond(
+    threadId: string,
+    enabled: boolean,
+    fallbackSessionId: string,
+  ): string {
+    const current = this._threadState.get(threadId);
+    const sessionId = current?.session_id ?? fallbackSessionId;
+    this._threadState.set(threadId, {
+      session_id: sessionId,
+      auto_respond: enabled,
+    });
+    const flag = enabled ? 1 : 0;
+    this._db
+      .insert(feishuThreads)
+      .values({
+        thread_id: threadId,
+        session_id: sessionId,
+        created_at: Date.now(),
+        auto_respond: flag,
+      })
+      .onConflictDoUpdate({
+        target: feishuThreads.thread_id,
+        set: { auto_respond: flag },
+      })
+      .run();
+    return sessionId;
+  }
 
   /** Persist a thread→session mapping to DB and update the in-memory cache. */
   private _mapThreadToSession(threadId: string, sessionId: string) {
-    this._threadIdToSessionId.set(threadId, sessionId);
+    const existing = this._threadState.get(threadId);
+    if (!existing) {
+      this._threadState.set(threadId, {
+        session_id: sessionId,
+        auto_respond: false,
+      });
+    }
     this._db
       .insert(feishuThreads)
       .values({
         thread_id: threadId,
         session_id: sessionId,
         created_at: Date.now(),
+        auto_respond: 0,
       })
       .onConflictDoNothing()
       .run();
   }
 
-  /** Resolve a session ID from a thread ID, falling back to DB then generating a new one. */
-  private _resolveSessionId(threadId: string | undefined): string {
-    if (threadId && this._threadIdToSessionId.has(threadId)) {
-      return this._threadIdToSessionId.get(threadId)!;
-    }
+  /**
+   * Resolve session id for an inbound Feishu message.
+   *
+   * Lookup order:
+   * 1. In-memory thread→session cache
+   * 2. `feishu_threads` DB mapping (populated when the bot replies and Feishu
+   *    creates a new thread — see `_mapThreadToSession`)
+   * 3. When both chat_id + thread_id are known, derive deterministically as
+   *    `feishu:<chat>:<thread>` and persist that mapping so subsequent lookups
+   *    short-circuit.
+   * 4. Fall back to `uuid()` when no thread_id (first @mention outside any
+   *    topic).
+   */
+  private _resolveSessionId(
+    chatId: string | undefined,
+    threadId: string | undefined,
+  ): string {
     if (threadId) {
+      const cached = this._threadState.get(threadId);
+      if (cached) return cached.session_id;
       const row = this._db
-        .select({ session_id: feishuThreads.session_id })
+        .select({
+          session_id: feishuThreads.session_id,
+          auto_respond: feishuThreads.auto_respond,
+        })
         .from(feishuThreads)
         .where(eq(feishuThreads.thread_id, threadId))
         .get();
       if (row) {
-        this._threadIdToSessionId.set(threadId, row.session_id);
+        this._threadState.set(threadId, {
+          session_id: row.session_id,
+          auto_respond: row.auto_respond === 1,
+        });
         return row.session_id;
       }
+      if (chatId) {
+        const derived = `feishu:${chatId}:${threadId}`;
+        this._mapThreadToSession(threadId, derived);
+        return derived;
+      }
     }
     return uuid();
   }
 
+  /**
+   * Pull the message the user reply-quoted so Claude can see what the new
+   * message is actually *about*. Returns a normalized `QuotedInfo` or
+   * `null` if the message can't be read (recalled, permission missing,
+   * network error) — callers should render a "消息已撤回或无法读取"
+   * placeholder in that case, not pretend the quote wasn't there.
+   */
+  private async _fetchQuotedMessage(
+    parentId: string,
+    targetDir?: string,
+  ): Promise<_QuotedInfo | null> {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK types are thin here
+      const res = await (this._client.im.message as any).get({
+        path: { message_id: parentId },
+      });
+      const item = res?.data?.items?.[0] as
+        | {
+            msg_type?: string;
+            create_time?: string;
+            sender?: { id?: string; id_type?: string };
+            body?: { content?: string };
+          }
+        | undefined;
+      if (!item) return null;
+      const msgType = item.msg_type ?? "unknown";
+      const createdAt = item.create_time
+        ? Number(item.create_time)
+        : undefined;
+      const senderOpenId =
+        item.sender?.id_type === "open_id" ? item.sender.id : undefined;
+      const text = await this._extractQuotedText(
+        parentId,
+        msgType,
+        item.body?.content ?? "{}",
+        targetDir,
+      );
+      return {
+        message_id: parentId,
+        message_type: msgType,
+        sender_open_id: senderOpenId,
+        created_at: createdAt,
+        text,
+      };
+    } catch (err) {
+      this._logger.warn(
+        { err, message_id: parentId },
+        "failed to fetch quoted message",
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Reduce a quoted message to a single text representation. Text/post
+   * get extracted verbatim; opaque types (image, file, card, sticker…)
+   * get a human-readable placeholder so Claude can still reason about
+   * "what did the user point at" without needing to download the asset.
+   */
+  private async _extractQuotedText(
+    messageId: string,
+    type: string,
+    rawContent: string,
+    targetDir?: string,
+  ): Promise<string> {
+    let json: Record<string, unknown>;
+    try {
+      json = JSON.parse(rawContent) as Record<string, unknown>;
+    } catch {
+      return "[无法解析的消息内容]";
+    }
+    if (type === "text") {
+      return typeof json.text === "string" ? json.text : "";
+    }
+    if (type === "post") {
+      try {
+        return await convertPostToMarkdown(json, (file_key) =>
+          this.downloadMessageResource(messageId, file_key, { targetDir }),
+        );
+      } catch {
+        return "[富文本消息]";
+      }
+    }
+    if (type === "image") {
+      // Download + embed as markdown image so Claude Code's multimodal
+      // pipeline picks it up, same way a directly-uploaded image works.
+      try {
+        const fileKey =
+          typeof json.image_key === "string" ? json.image_key : null;
+        if (!fileKey) return "[图片]";
+        const path = await this.downloadMessageResource(messageId, fileKey, {
+          targetDir,
+        });
+        return `![quoted_image](${path})`;
+      } catch (err) {
+        this._logger.warn(
+          { err, message_id: messageId },
+          "failed to download quoted image",
+        );
+        return "[图片(下载失败)]";
+      }
+    }
+    if (type === "file") {
+      const name = typeof json.file_name === "string" ? json.file_name : "";
+      return name ? `[文件: ${name}]` : "[文件]";
+    }
+    if (type === "audio") return "[语音]";
+    if (type === "media") return "[视频]";
+    if (type === "sticker") return "[表情]";
+    if (type === "interactive") return "[卡片]";
+    return `[${type} 消息]`;
+  }
+
   private async _parseMessageContent(
     messageId: string,
     type: string,
     content: string,
+    targetDir?: string,
   ): Promise<TextMessageContent> {
     const json = JSON.parse(content);
     if (type === "text") {
@@ -622,9 +1730,8 @@ export class FeishuMessageChannel
         text: json.text,
       };
     } else if (type === "post") {
-      const markdown = await convertPostToMarkdown(
-        json,
-        this.downloadMessageResource.bind(this, messageId),
+      const markdown = await convertPostToMarkdown(json, (file_key) =>
+        this.downloadMessageResource(messageId, file_key, { targetDir }),
       );
       return {
         type: "text",
@@ -632,7 +1739,9 @@ export class FeishuMessageChannel
       };
     } else if (type === "image") {
       const file_key = json.image_key as string;
-      const path = await this.downloadMessageResource(messageId, file_key);
+      const path = await this.downloadMessageResource(messageId, file_key, {
+        targetDir,
+      });
       return {
         type: "text",
         text: `![user_uploaded_image](${path})`,
@@ -640,11 +1749,10 @@ export class FeishuMessageChannel
     } else if (type === "file") {
       const file_key = json.file_key as string;
       const file_name = json.file_name as string;
-      const path = await this.downloadMessageResource(
-        messageId,
-        file_key,
+      const path = await this.downloadMessageResource(messageId, file_key, {
         file_name,
-      );
+        targetDir,
+      });
       return {
         type: "text",
         text: `A new file message uploaded to \`${path}\``,
@@ -655,3 +1763,97 @@ export class FeishuMessageChannel
     }
   }
 }
+
+/**
+ * Normalized shape of a reply-quoted Feishu message, ready to format
+ * into a `<quoted_message>` block.
+ */
+interface _QuotedInfo {
+  message_id: string;
+  message_type: string;
+  sender_open_id?: string;
+  created_at?: number;
+  text: string;
+}
+
+/** Max characters of quoted text surfaced to Claude. */
+const _QUOTED_TEXT_MAX_CHARS = 500;
+
+/**
+ * Format a quoted message as a structured `<quoted_message>` block the
+ * agent can reason about. Pass `null` to render a "revoked / unreadable"
+ * placeholder block — the agent still sees that a quote existed, which
+ * is better than silently dropping the signal.
+ */
+function _formatQuotedBlock(
+  info: _QuotedInfo | null,
+  parentId?: string,
+): string {
+  if (info === null) {
+    const idAttr = parentId ? ` id="${_escapeAttr(parentId)}"` : "";
+    return (
+      `<quoted_message${idAttr} status="unavailable">\n` +
+      `[该消息已撤回或无法读取]\n` +
+      `</quoted_message>`
+    );
+  }
+  const attrs: string[] = [
+    `id="${_escapeAttr(info.message_id)}"`,
+    `type="${_escapeAttr(info.message_type)}"`,
+  ];
+  if (info.sender_open_id) {
+    attrs.push(`author_open_id="${_escapeAttr(info.sender_open_id)}"`);
+  }
+  if (info.created_at) {
+    attrs.push(`time="${new Date(info.created_at).toISOString()}"`);
+  }
+  const { text, truncated } = _truncateQuotedText(
+    info.text,
+    _QUOTED_TEXT_MAX_CHARS,
+  );
+  if (truncated) attrs.push(`truncated="true"`);
+  return (
+    `<quoted_message ${attrs.join(" ")}>\n` + text + `\n</quoted_message>`
+  );
+}
+
+/** Clip quoted text to a char budget; append an ellipsis when trimmed. */
+function _truncateQuotedText(
+  text: string,
+  maxChars: number,
+): { text: string; truncated: boolean } {
+  if (text.length <= maxChars) return { text, truncated: false };
+  return { text: text.slice(0, maxChars - 1) + "…", truncated: true };
+}
+
+/** Escape a string for safe use inside an XML attribute. */
+function _escapeAttr(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+/**
+ * Cheap check for whether an inbound Feishu message looks like a slash
+ * command, so we can skip the @-mention requirement for those. We only
+ * inspect raw `text` content — post/image/file messages are never
+ * considered slash commands. Parsing failures → treat as non-slash.
+ */
+function _peekSlashCommand(type: string, content: string): boolean {
+  if (type !== "text") return false;
+  try {
+    const json = JSON.parse(content) as { text?: unknown };
+    if (typeof json.text !== "string") return false;
+    // Strip leading @_user_N placeholder runs — users habitually @ the
+    // bot before typing a slash command inside a thread, and the
+    // placeholder would otherwise hide the `/` prefix.
+    const text = json.text
+      .trimStart()
+      .replace(/^(?:@_user_\d+\s*)+/, "");
+    return /^\/[a-zA-Z]/.test(text);
+  } catch {
+    return false;
+  }
+}
diff --git a/src/community/feishu/messaging/message-renderer.ts b/src/community/feishu/messaging/message-renderer.ts
index 39a4c06..f34d009 100644
--- a/src/community/feishu/messaging/message-renderer.ts
+++ b/src/community/feishu/messaging/message-renderer.ts
@@ -5,6 +5,7 @@ import {
   config,
   type AssistantMessage,
   type BashToolUseMessageContent,
+  type CardFooterStats,
   type EditToolUseMessageContent,
   type GlobToolUseMessageContent,
   type GrepToolUseMessageContent,
@@ -26,10 +27,60 @@ import type {
 /** Maximum elements or components in one Feishu card. */
 const MAX_FEISHU_CARD_ELEMENTS = 200;
 
+/**
+ * Maximum step-panel elements per card. A single Feishu container is
+ * capped at 50 server-side (error 11310 `element exceeds the limit`); we
+ * keep cards well under that so long runs don't get rejected. The panel
+ * shows the most recent N-1 steps plus a single "… K earlier steps" row
+ * pinned at the top when the true count exceeds this cap.
+ */
+export const MAX_STEPS_PER_CARD = 25;
+
+/**
+ * Per-step text clip length. Agent output frequently contains huge Bash
+ * descriptions or multi-KB thinking traces; displayed as-is they'd push
+ * the card past Feishu's 30 KB body cap on their own. Each step's text
+ * is truncated to at most this many characters (first line only) so the
+ * panel stays legible — the full payload is always preserved in the
+ * session jsonl for post-hoc inspection.
+ */
+export const MAX_STEP_TEXT_CHARS = 200;
+
+/**
+ * Byte budget for a single card's markdown text block. Above this we
+ * spill the overflow into follow-up text-only cards.
+ *
+ * Feishu's content ceiling is 30 KB. Budget breakdown on a fully
+ * populated card:
+ *   - card wrapper (config, body shell, headers): ~800 bytes
+ *   - step panel with 25 rows, per-step text clipped to 200 chars,
+ *     Chinese-filled worst case: ~8–10 KB (ASCII-heavy: ~5 KB)
+ *   - markdown block (in body.elements AND a short summary preview):
+ *     headroom → up to ~20 KB here
+ *
+ * The summary preview is intentionally short (see `_summarizeMarkdown`
+ * below) so we're not double-paying the markdown bytes.
+ */
+export const MAX_MARKDOWN_BYTES_PER_CHUNK = 20 * 1024;
+
+/**
+ * Max summary length (characters) shown in the Feishu notification /
+ * chat-list preview. Kept tiny — the full message lives in the body
+ * element; duplicating the whole markdown here would double the card's
+ * byte cost for no visible gain.
+ */
+const _SUMMARY_PREVIEW_CHARS = 180;
+
 /**
  * Render assistant message content as a Feishu interactive card.
  * @param messageContent - Array of content blocks (thinking, tool_use, text).
  * @param options - Rendering options (streaming mode).
+ *   - `elapsedMs`: optional response-duration hint in milliseconds. When
+ *     provided and `streaming` is false, the card renders a small grey
+ *     note at the bottom like "Done in 12.8s" so users can see how long
+ *     the run took.
+ *   - `footer`: optional context / quota stats rendered as small grey
+ *     progress bars beneath the "Done in" note on a finalized card.
  * @returns Feishu Card object for API payload.
  */
 export async function renderMessageCard(
@@ -37,10 +88,14 @@ export async function renderMessageCard(
   {
     streaming,
     uploadImage,
+    elapsedMs,
+    footer,
   }: {
     streaming: boolean;
     // eslint-disable-next-line no-unused-vars
     uploadImage: (path: string) => Promise<string>;
+    elapsedMs?: number;
+    footer?: CardFooterStats;
   },
 ): Promise<Card> {
   const stepPanel: CollapsiblePanel = {
@@ -91,6 +146,11 @@ export async function renderMessageCard(
       _renderTool(content, stepPanel);
     }
   }
+  // Capture the real step count *before* we drop oldest rows to fit the
+  // card — the header wants to show overall progress, not the windowed
+  // view size.
+  const trueStepCount = stepPanel.elements.length;
+  _truncateStepPanel(stepPanel);
   if (!streaming) {
     // Find the last text block (final response), not all text blocks
     const lastTextContent = messageContent.findLast((c) => c.type === "text");
@@ -105,15 +165,14 @@ export async function renderMessageCard(
         tag: "markdown",
         content: markdownContent,
       };
-      card.config!.summary.content = markdownContent;
+      card.config!.summary.content = _summarizeMarkdown(markdownContent);
       card.body.elements.push(resultElement);
     }
   }
 
-  const totalStepCount = stepPanel.elements.length;
-  if (totalStepCount > 0) {
+  if (trueStepCount > 0) {
     const stepCountText =
-      totalStepCount + " " + (totalStepCount === 1 ? "step" : "steps");
+      trueStepCount + " " + (trueStepCount === 1 ? "step" : "steps");
     if (streaming) {
       stepPanel.header.title.content = `Working on it (${stepCountText})`;
       card.config!.summary.content = `Working on it (${stepCountText})`;
@@ -144,6 +203,23 @@ export async function renderMessageCard(
         color: "grey",
       },
     });
+  } else {
+    const footerLines: string[] = [];
+    if (typeof elapsedMs === "number" && elapsedMs >= 0) {
+      footerLines.push(`Done in ${_formatDuration(elapsedMs)}`);
+    }
+    footerLines.push(..._renderFooterStats(footer));
+    if (footerLines.length > 0) {
+      card.body.elements.push({
+        tag: "div",
+        text: {
+          tag: "plain_text",
+          text_color: "grey",
+          text_size: "notation",
+          content: footerLines.join("\n"),
+        },
+      });
+    }
   }
   _trimCardElements(card);
   return card;
@@ -185,6 +261,111 @@ function _countElements(value: unknown): number {
   );
 }
 
+/** Fixed width (in cells) of every footer progress bar. */
+const FOOTER_BAR_WIDTH = 12;
+
+/**
+ * Build the context / quota progress-bar lines for the card footer. Each
+ * line is `<label> <bar> <pct>% <detail>`, with labels padded to a common
+ * width so the bars line up. Returns an empty list when no stats apply.
+ */
+function _renderFooterStats(footer?: CardFooterStats): string[] {
+  if (!footer) return [];
+  const lines: string[] = [];
+  if (footer.model) {
+    lines.push(`${_padLabel("Model")} ${footer.model}`);
+  }
+  if (footer.context) {
+    const { used_tokens, limit_tokens } = footer.context;
+    const pct = limit_tokens > 0 ? (used_tokens / limit_tokens) * 100 : 0;
+    lines.push(
+      `${_padLabel("Context")} ${_renderBar(pct)} ${_formatPercent(pct)}  ` +
+        `${_formatTokens(used_tokens)}/${_formatTokens(limit_tokens)}`,
+    );
+  }
+  if (footer.five_hour) {
+    lines.push(
+      `${_padLabel("5h limit")} ${_renderBar(footer.five_hour.utilization)} ` +
+        `${_formatPercent(footer.five_hour.utilization)}` +
+        `${_formatResetsIn(footer.five_hour.resets_at)}`,
+    );
+  }
+  if (footer.seven_day) {
+    lines.push(
+      `${_padLabel("Weekly")} ${_renderBar(footer.seven_day.utilization)} ` +
+        `${_formatPercent(footer.seven_day.utilization)}` +
+        `${_formatResetsIn(footer.seven_day.resets_at)}`,
+    );
+  }
+  return lines;
+}
+
+/** Right-pad a footer label to a common width so bars align. */
+function _padLabel(label: string): string {
+  return label.padEnd(8, " ");
+}
+
+/** Clamp a 0..100 percentage and render it as a block-character bar. */
+function _renderBar(pct: number, width: number = FOOTER_BAR_WIDTH): string {
+  const clamped = Math.max(0, Math.min(100, pct));
+  const filled = Math.round((clamped / 100) * width);
+  return "█".repeat(filled) + "░".repeat(width - filled);
+}
+
+/** Render a percentage as an integer with a trailing `%`. */
+function _formatPercent(pct: number): string {
+  return `${Math.round(Math.max(0, Math.min(100, pct)))}%`;
+}
+
+/** Compact token count, e.g. 76000 -> "76k", 1500 -> "1.5k", 1e6 -> "1M". */
+function _formatTokens(n: number): string {
+  if (n >= 1_000_000) {
+    const m = n / 1_000_000;
+    return Number.isInteger(m) ? `${m}M` : `${m.toFixed(1)}M`;
+  }
+  if (n < 1000) return `${n}`;
+  const k = n / 1000;
+  if (k >= 100 || Number.isInteger(k)) return `${Math.round(k)}k`;
+  return `${k.toFixed(1)}k`;
+}
+
+/**
+ * Human-friendly " · resets in 2h 13m" suffix from an ISO timestamp.
+ * Returns an empty string when the reset time is unknown or already past.
+ */
+function _formatResetsIn(resetsAt: string | null): string {
+  if (!resetsAt) return "";
+  const diffMs = new Date(resetsAt).getTime() - Date.now();
+  if (!Number.isFinite(diffMs) || diffMs <= 0) return " · resets soon";
+  const totalMinutes = Math.floor(diffMs / 60000);
+  const days = Math.floor(totalMinutes / 1440);
+  const hours = Math.floor((totalMinutes % 1440) / 60);
+  const minutes = totalMinutes % 60;
+  if (days > 0) return ` · resets in ${days}d ${hours}h`;
+  if (hours > 0) return ` · resets in ${hours}h ${minutes}m`;
+  return ` · resets in ${minutes}m`;
+}
+
+/**
+ * Human-friendly duration string for the card's "Done in …" note.
+ * Sub-second runs round to 0.1s; sub-minute shows a single decimal;
+ * minutes drop the decimal and pad seconds; hours add an `h` prefix.
+ */
+function _formatDuration(ms: number): string {
+  const totalSeconds = ms / 1000;
+  if (totalSeconds < 60) {
+    return `${totalSeconds.toFixed(1)}s`;
+  }
+  const totalSecondsInt = Math.floor(totalSeconds);
+  const hours = Math.floor(totalSecondsInt / 3600);
+  const minutes = Math.floor((totalSecondsInt % 3600) / 60);
+  const seconds = totalSecondsInt % 60;
+  if (hours === 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${hours}h ${minutes}m ${seconds}s`;
+}
+
 async function _uploadMessageResource(
   text: string,
   {
@@ -212,18 +393,21 @@ async function _uploadMessageResource(
               fs.mkdirSync(downloadPath, { recursive: true });
             }
             if (imageName) {
-              fs.writeFileSync(
-                nodePath.join(downloadPath, imageName),
-                Buffer.from(imageBuffer),
-              );
-              imagePath = nodePath.join("workspace", "downloads", imageName);
+              imagePath = nodePath.join(downloadPath, imageName);
+              fs.writeFileSync(imagePath, Buffer.from(imageBuffer));
             }
           } catch {
             text = text.replaceAll(image, `[${imagePath}](${imagePath})`);
           }
         }
-        if (fs.existsSync(nodePath.join(config.paths.home, imagePath))) {
-          const imageKey = await uploadImage(imagePath);
+        // Paths may be absolute (Feishu downloads, since we moved away
+        // from relative-to-HOME) or relative-to-home (legacy sessions,
+        // markdown written by agents using the old scheme).
+        const absPath = nodePath.isAbsolute(imagePath)
+          ? imagePath
+          : nodePath.join(config.paths.home, imagePath);
+        if (fs.existsSync(absPath)) {
+          const imageKey = await uploadImage(absPath);
           text = text.replaceAll(image, `![image](${imageKey})`);
         } else {
           text = text.replaceAll(image, "");
@@ -340,6 +524,61 @@ function _renderTool(
   }
 }
 
+/**
+ * Drop oldest rows from the step panel when the true step count exceeds
+ * Feishu's safe container size. Keeps the most recent
+ * `MAX_STEPS_PER_CARD - 1` rows and prepends a single summary row like
+ * `… 42 earlier steps` so the user sees both what just happened and
+ * how much came before it.
+ */
+function _truncateStepPanel(stepPanel: CollapsiblePanel): void {
+  const total = stepPanel.elements.length;
+  if (total <= MAX_STEPS_PER_CARD) return;
+  const kept = MAX_STEPS_PER_CARD - 1;
+  const dropped = total - kept;
+  const tail = stepPanel.elements.slice(-kept);
+  stepPanel.elements = [
+    _renderStep(`… ${dropped} earlier steps`, "more_outlined"),
+    ...tail,
+  ];
+}
+
+/**
+ * Build a short preview of the final markdown for `config.summary.content`
+ * (Feishu notifications / chat list snippet). Keep it tight — the full
+ * markdown is already in body.elements, so duplicating it here just
+ * doubles the card's byte cost for no visible benefit.
+ */
+function _summarizeMarkdown(markdown: string): string {
+  const trimmed = markdown.trim();
+  if (trimmed.length === 0) return "";
+  const firstLineEnd = trimmed.indexOf("\n");
+  const firstLine = firstLineEnd === -1 ? trimmed : trimmed.slice(0, firstLineEnd);
+  if (firstLine.length <= _SUMMARY_PREVIEW_CHARS) {
+    return firstLineEnd === -1 ? firstLine : firstLine + " …";
+  }
+  return firstLine.slice(0, _SUMMARY_PREVIEW_CHARS - 1) + "…";
+}
+
+/**
+ * Clip a step's display text so the panel stays legible even when the
+ * underlying tool use carries a huge Bash command or a multi-KB thinking
+ * trace. Takes the first line (up to `maxChars`) and appends an ellipsis
+ * when anything was dropped.
+ */
+function _clipStepText(
+  text: string,
+  maxChars: number = MAX_STEP_TEXT_CHARS,
+): string {
+  const firstLineEnd = text.indexOf("\n");
+  const firstLine = firstLineEnd === -1 ? text : text.slice(0, firstLineEnd);
+  const hadMoreLines = firstLineEnd !== -1;
+  if (firstLine.length <= maxChars) {
+    return hadMoreLines ? firstLine + " …" : firstLine;
+  }
+  return firstLine.slice(0, maxChars - 1) + "…";
+}
+
 /** Create a step element (icon + text) for the collapsible panel. */
 function _renderStep(text: string, iconToken: string): DivElement {
   return {
@@ -353,7 +592,7 @@ function _renderStep(text: string, iconToken: string): DivElement {
       tag: "plain_text",
       text_color: "grey",
       text_size: "notation",
-      content: text,
+      content: _clipStepText(text),
     },
   };
 }
@@ -423,3 +662,83 @@ export function splitMarkdownByTables(
 
   return chunks;
 }
+
+/**
+ * Split markdown into byte-bounded chunks so a single final answer
+ * doesn't overflow Feishu's 30 KB card body. Splits are preferred at
+ * paragraph boundaries (blank lines) to keep chunks readable; if a
+ * single paragraph is itself larger than `maxBytes`, falls back to line
+ * boundaries, then to a hard character slice as last resort.
+ *
+ * The returned chunks together reproduce the input verbatim, with
+ * inter-chunk whitespace trimmed at the split points.
+ */
+export function splitMarkdownByBytes(
+  markdown: string,
+  maxBytes: number = MAX_MARKDOWN_BYTES_PER_CHUNK,
+): string[] {
+  if (Buffer.byteLength(markdown, "utf8") <= maxBytes) {
+    return [markdown];
+  }
+  const chunks: string[] = [];
+  let current = "";
+  const flush = () => {
+    if (current.trim().length > 0) chunks.push(current.trim());
+    current = "";
+  };
+  const appendWithSeparator = (piece: string, sep: string) => {
+    const combined = current ? current + sep + piece : piece;
+    if (Buffer.byteLength(combined, "utf8") <= maxBytes) {
+      current = combined;
+    } else {
+      flush();
+      if (Buffer.byteLength(piece, "utf8") <= maxBytes) {
+        current = piece;
+      } else {
+        // Piece itself is oversized — emit as-is so no content is lost.
+        // Callers should expect this chunk to be over budget; downstream
+        // Feishu may still reject it, but that's a degenerate case worth
+        // surfacing as-is rather than silently dropping.
+        chunks.push(piece);
+        current = "";
+      }
+    }
+  };
+
+  const paragraphs = markdown.split(/\n\s*\n/);
+  for (const para of paragraphs) {
+    if (Buffer.byteLength(para, "utf8") <= maxBytes) {
+      appendWithSeparator(para, "\n\n");
+      continue;
+    }
+    // Paragraph itself too big — fall back to splitting by line.
+    flush();
+    const lines = para.split("\n");
+    for (const line of lines) {
+      appendWithSeparator(line, "\n");
+    }
+  }
+  flush();
+  return chunks;
+}
+
+/**
+ * Compose markdown splitters: first enforce the table-per-card cap
+ * (Feishu renders at most 5 table components), then enforce the byte
+ * cap per chunk. Result is a flat list of markdown strings each
+ * individually safe to put on a single Feishu card.
+ */
+export function splitMarkdownForCards(
+  markdown: string,
+  {
+    maxTables = 5,
+    maxBytes = MAX_MARKDOWN_BYTES_PER_CHUNK,
+  }: { maxTables?: number; maxBytes?: number } = {},
+): string[] {
+  const tableChunks = splitMarkdownByTables(markdown, maxTables);
+  const out: string[] = [];
+  for (const chunk of tableChunks) {
+    out.push(...splitMarkdownByBytes(chunk, maxBytes));
+  }
+  return out;
+}
diff --git a/src/community/feishu/messaging/types/interactive/elements.ts b/src/community/feishu/messaging/types/interactive/elements.ts
index d674686..d694c8c 100644
--- a/src/community/feishu/messaging/types/interactive/elements.ts
+++ b/src/community/feishu/messaging/types/interactive/elements.ts
@@ -76,9 +76,116 @@ export interface CollapsiblePanel extends BaseContainer<"collapsible_panel"> {
   };
 }
 
+/**
+ * Generic callback value on an interactive element. Our `/setup` flow uses
+ * `{ action: string; setup_id: string; ... }`, but we keep the shape open so
+ * future interactive commands can attach whatever discriminator they need.
+ * The server receives this verbatim on `card.action.trigger`.
+ */
+export type CallbackValue = Record<string, unknown>;
+
+export interface CallbackBehavior {
+  type: "callback";
+  value: CallbackValue;
+}
+
+/**
+ * Button. Two modes:
+ * - `action_type: "form_submit"` — submits the enclosing form; the triggered
+ *   action payload includes `form_value` (a map of every named input/checker
+ *   inside the form).
+ * - no `action_type` + `behaviors: [{ type: "callback", value }]` — a standalone
+ *   callback that delivers `value` as `action.value` on the server event.
+ */
+export interface ButtonElement extends BaseElement<"button"> {
+  name?: string;
+  text: PlainTextElement;
+  type?: "default" | "primary" | "danger" | "text";
+  action_type?: "form_submit" | "form_reset";
+  behaviors?: CallbackBehavior[];
+  width?: string;
+}
+
+/**
+ * Single-line text input. `name` is the field key echoed back in the form
+ * submission's `form_value`.
+ */
+export interface InputElement extends BaseElement<"input"> {
+  name: string;
+  placeholder?: PlainTextElement;
+  default_value?: string;
+  width?: string;
+  max_length?: number;
+}
+
+/**
+ * Single toggle checkbox. `name` is the field key; `checked` is the initial
+ * state; on form submission, the server echoes a boolean at `form_value[name]`.
+ *
+ * Note: Feishu requires `text` to be `plain_text`. Passing `markdown` yields
+ * "type of element is not supported tag: markdown" (error 200621).
+ */
+export interface CheckerElement extends BaseElement<"checker"> {
+  name: string;
+  text: PlainTextElement;
+  checked?: boolean;
+  disabled?: boolean;
+}
+
+export interface SelectOption {
+  text: PlainTextElement;
+  value: string;
+}
+
+/**
+ * Single-select dropdown. On form submission the selected `value` is echoed at
+ * `form_value[name]`.
+ */
+export interface SelectStaticElement extends BaseElement<"select_static"> {
+  name: string;
+  placeholder?: PlainTextElement;
+  initial_option?: string;
+  options: SelectOption[];
+  width?: string;
+}
+
+/** One column inside a `column_set`. */
+export interface Column extends BaseContainer<"column"> {
+  width?: "auto" | "weighted" | "fill" | string;
+  weight?: number;
+  vertical_align?: "top" | "center" | "bottom";
+  vertical_spacing?: string;
+  padding?: string;
+}
+
+/**
+ * Horizontal row of columns. Useful for placing a checker next to its input
+ * and description on a single card row.
+ */
+export interface ColumnSetElement extends BaseElement<"column_set"> {
+  flex_mode?: "none" | "stretch" | "flow" | "bisect" | "trisect";
+  horizontal_spacing?: string;
+  columns: Column[];
+}
+
+/**
+ * Form container. Any inputs/checkers/buttons placed inside contribute to the
+ * form's `form_value` on submit. `name` identifies the form on the server side.
+ */
+export interface FormElement extends BaseContainer<"form"> {
+  name: string;
+}
+
 export type Element =
+  | ButtonElement
+  | CheckerElement
   | CollapsiblePanel
+  | Column
+  | ColumnSetElement
   | DivElement
+  | FormElement
   | IconElement
+  | InputElement
   | MarkdownElement
-  | PlainTextElement;
+  | PlainTextElement
+  | SelectStaticElement;
diff --git a/src/community/openai/codex-agent-runner.ts b/src/community/openai/codex-agent-runner.ts
index 7cfb9fd..2031bf3 100644
--- a/src/community/openai/codex-agent-runner.ts
+++ b/src/community/openai/codex-agent-runner.ts
@@ -5,6 +5,7 @@ import {
   config,
   createLogger,
   extractTextContent,
+  inlineMentions,
   resolveInstructionFile,
   uuid,
   type ToolMessage,
@@ -17,6 +18,19 @@ import {
 
 const logger = createLogger("codex-agent-runner");
 
+export interface CodexAgentRunnerOptions {
+  extraGlobalArgs?: string[];
+  extraExecArgs?: string[];
+}
+
+interface CodexSpawnOptions {
+  args: string[];
+  cwd: string;
+  env: Record<string, string | undefined>;
+  signal?: AbortSignal;
+  sessionId: string;
+}
+
 /**
  * Error thrown when the agent runner is aborted.
  */
@@ -27,6 +41,21 @@ export class AgentAbortError extends Error {
   }
 }
 
+export class CodexMissingResumeError extends Error {
+  readonly causeError: unknown;
+
+  constructor(
+    readonly resumeId: string,
+    causeError: unknown,
+  ) {
+    super(
+      `Codex 无法续接本地 thread：${resumeId}。请确认是否重新开始 Codex 会话。`,
+    );
+    this.name = "CodexMissingResumeError";
+    this.causeError = causeError;
+  }
+}
+
 /**
  * The agent runner for OpenAI Codex CLI.
  *
@@ -36,6 +65,11 @@ export class AgentAbortError extends Error {
  */
 export class CodexAgentRunner implements AgentRunner {
   readonly type = "codex";
+  private readonly _options: CodexAgentRunnerOptions;
+
+  constructor(options: CodexAgentRunnerOptions = {}) {
+    this._options = options;
+  }
 
   async *stream(
     message: UserMessage,
@@ -46,7 +80,7 @@ export class CodexAgentRunner implements AgentRunner {
     const signal = options?.signal;
     const resumeId = options.runnerSessionId ?? sessionId;
     const textContentOfUserMessage = JSON.stringify(
-      extractTextContent(message),
+      inlineMentions(extractTextContent(message), message.mentions),
     );
 
     // Sync CLAUDE.md → AGENTS.md on every invocation so Codex CLI always
@@ -59,27 +93,64 @@ export class CodexAgentRunner implements AgentRunner {
       prompt: textContentOfUserMessage,
     });
 
-    const proc = Bun.spawn(args, {
+    // Gated by `agents.codex.isolate_host_env` — off by default,
+    // in which case Codex inherits the host env verbatim.  When on,
+    // CODEX_HOME is redirected so config / sessions / state stay
+    // separate from the host's `~/.codex/`.  Host hook behavior is
+    // not touched here — Codex always climbs cwd ancestors for
+    // `.codex/hooks.json` regardless of CODEX_HOME, so keep your
+    // global hooks.json out of `~/.codex/` if you do not want it
+    // firing under agentara workspaces.
+    const isolationEnv = config.agents.codex.isolate_host_env
+      ? { CODEX_HOME: config.paths.codex_home }
+      : {};
+    const env = {
+      ...Bun.env,
+      ...config.agents.env,
+      ...isolationEnv,
+      ...(options.envExtras ?? {}),
+    };
+
+    try {
+      yield* this._streamCodexProcess({
+        args,
+        cwd: options.cwd,
+        env,
+        signal,
+        sessionId,
+      });
+    } catch (err) {
+      if (!isNew && this._isMissingResumeError(err)) {
+        throw new CodexMissingResumeError(resumeId, err);
+      }
+      throw err;
+    }
+  }
+
+  private async *_streamCodexProcess(
+    options: CodexSpawnOptions,
+  ): AsyncIterableIterator<SystemMessage | AssistantMessage | ToolMessage> {
+    const proc = Bun.spawn(options.args, {
       cwd: options.cwd,
-      env: {
-        ...Bun.env,
-      },
+      env: options.env,
       stderr: "pipe",
     });
-
     // Handle abort signal
     let aborted = false;
     const abortHandler = () => {
       aborted = true;
-      logger.info({ session_id: sessionId }, "killing Codex CLI process");
+      logger.info(
+        { session_id: options.sessionId },
+        "killing Codex CLI process",
+      );
       proc.kill();
     };
-    if (signal) {
-      if (signal.aborted) {
+    if (options.signal) {
+      if (options.signal.aborted) {
         proc.kill();
         throw new AgentAbortError();
       }
-      signal.addEventListener("abort", abortHandler, { once: true });
+      options.signal.addEventListener("abort", abortHandler, { once: true });
     }
 
     const decoder = new TextDecoder();
@@ -106,7 +177,10 @@ export class CodexAgentRunner implements AgentRunner {
         buffer = lines.pop()!;
         for (const line of lines) {
           if (line.trim()) {
-            const messages = this._parseStreamLine(line.trim(), sessionId);
+            const messages = this._parseStreamLine(
+              line.trim(),
+              options.sessionId,
+            );
             for (const msg of messages) {
               yield msg;
             }
@@ -115,14 +189,14 @@ export class CodexAgentRunner implements AgentRunner {
       }
 
       if (!aborted && buffer.trim()) {
-        const messages = this._parseStreamLine(buffer.trim(), sessionId);
+        const messages = this._parseStreamLine(buffer.trim(), options.sessionId);
         for (const msg of messages) {
           yield msg;
         }
       }
     } finally {
-      if (signal) {
-        signal.removeEventListener("abort", abortHandler);
+      if (options.signal) {
+        options.signal.removeEventListener("abort", abortHandler);
       }
     }
 
@@ -137,15 +211,7 @@ export class CodexAgentRunner implements AgentRunner {
         stderrChunks.length > 0
           ? decoder.decode(Bun.concatArrayBuffers(stderrChunks))
           : "";
-      const parts: string[] = [];
-      if (stdoutRaw.trim()) {
-        parts.push(`Stdout:\n${stdoutRaw.trim()}`);
-      }
-      if (stderrText.trim()) {
-        parts.push(`Stderr:\n${stderrText.trim()}`);
-      }
-      const detail = parts.length > 0 ? `\n\n${parts.join("\n\n")}` : "";
-      throw new Error(`Codex CLI exited with code ${exitCode}${detail}`);
+      throw new CodexCliExitError(exitCode, stdoutRaw, stderrText);
     }
   }
 
@@ -475,13 +541,18 @@ export class CodexAgentRunner implements AgentRunner {
     resumeId: string;
     prompt: string;
   }): string[] {
+    const configuredModel = config.agents.default.model;
     const shared = [
       "codex",
+      ...(this._options.extraGlobalArgs ?? []),
       "exec",
-      ...["--model", config.agents.default.model],
+      // Only pin the model when config names one; otherwise Codex CLI
+      // picks its own default (user omitted `model` in config.yaml).
+      ...(configuredModel ? ["--model", configuredModel] : []),
       "--json",
       "--dangerously-bypass-approvals-and-sandbox",
       "--skip-git-repo-check",
+      ...(this._options.extraExecArgs ?? []),
     ];
     if (isNew) {
       return [...shared, prompt];
@@ -489,6 +560,18 @@ export class CodexAgentRunner implements AgentRunner {
     return [...shared, "resume", resumeId, prompt];
   }
 
+  private _isMissingResumeError(err: unknown): boolean {
+    if (!(err instanceof CodexCliExitError)) return false;
+    return this._isMissingResumeErrorText(err.stderr);
+  }
+
+  private _isMissingResumeErrorText(text: string): boolean {
+    return (
+      text.includes("thread/resume failed") &&
+      text.includes("no rollout found for thread id")
+    );
+  }
+
   /**
    * Reads `CLAUDE.md` from `cwd`, resolves any `@path/file` imports, and
    * writes the result as `AGENTS.md` so the Codex CLI can pick it up as its
@@ -525,3 +608,22 @@ export class CodexAgentRunner implements AgentRunner {
     }
   }
 }
+
+class CodexCliExitError extends Error {
+  constructor(
+    readonly exitCode: number,
+    readonly stdout: string,
+    readonly stderr: string,
+  ) {
+    const parts: string[] = [];
+    if (stdout.trim()) {
+      parts.push(`Stdout:\n${stdout.trim()}`);
+    }
+    if (stderr.trim()) {
+      parts.push(`Stderr:\n${stderr.trim()}`);
+    }
+    const detail = parts.length > 0 ? `\n\n${parts.join("\n\n")}` : "";
+    super(`Codex CLI exited with code ${exitCode}${detail}`);
+    this.name = "CodexCliExitError";
+  }
+}
diff --git a/src/kernel/agent-failure.ts b/src/kernel/agent-failure.ts
new file mode 100644
index 0000000..5cf9997
--- /dev/null
+++ b/src/kernel/agent-failure.ts
@@ -0,0 +1,31 @@
+import type { AssistantMessage } from "@/shared";
+
+export function buildAgentCancelledContent(): AssistantMessage["content"] {
+  return [
+    {
+      type: "text",
+      text: "⏹️ 任务已取消。",
+    },
+  ];
+}
+
+export function buildAgentFailureContent(
+  err: unknown,
+): AssistantMessage["content"] {
+  const message = err instanceof Error ? err.message : String(err);
+  const detail = message.trim() || "未知错误";
+  return [
+    {
+      type: "text",
+      text: [
+        "❌ Agent 启动或执行失败。",
+        "",
+        "```",
+        detail,
+        "```",
+        "",
+        "可以先检查当前 Agent 类型、代理/出口环境，或执行 `/agent use <type>` 后新开会话重试。",
+      ].join("\n"),
+    },
+  ];
+}
diff --git a/src/kernel/agents/aliases.ts b/src/kernel/agents/aliases.ts
new file mode 100644
index 0000000..8ecda9b
--- /dev/null
+++ b/src/kernel/agents/aliases.ts
@@ -0,0 +1,11 @@
+const LEGACY_AGENT_TYPE_ALIASES: Record<string, string> = {
+  "codex-gated": "codex-yolo",
+};
+
+export function resolveAgentTypeAlias(type: string): string {
+  return LEGACY_AGENT_TYPE_ALIASES[type] ?? type;
+}
+
+export function isLegacyAgentTypeAlias(type: string): boolean {
+  return LEGACY_AGENT_TYPE_ALIASES[type] !== undefined;
+}
diff --git a/src/kernel/agents/factory.ts b/src/kernel/agents/factory.ts
index c5b5e7d..25cd813 100644
--- a/src/kernel/agents/factory.ts
+++ b/src/kernel/agents/factory.ts
@@ -2,24 +2,26 @@ import { ClaudeAgentRunner } from "@/community/anthropic";
 import { CodexAgentRunner } from "@/community/openai";
 import { DummyAgentRunner, MockAgentRunner, type AgentRunner } from "@/shared";
 
+import { createRunner, registerRunner } from "./registry";
+
+// Register the built-in runners at module load. Plugins under `src/plugins`
+// are imported separately (see `src/plugins/index.ts`) and register
+// themselves by the same mechanism.
+registerRunner("claude", () => new ClaudeAgentRunner());
+registerRunner("codex", () => new CodexAgentRunner());
+registerRunner("dummy", () => new DummyAgentRunner());
+registerRunner(
+  "mock",
+  () =>
+    new MockAgentRunner(
+      "user-home/sessions/34681283-bf20-4dc4-8301-a0929104002e.jsonl",
+    ),
+);
+
 /**
- * Creates an agent runner based on the agent type.
- * @param agentType The type of the agent.
- * @returns The agent runner.
+ * Creates an agent runner based on the agent type. Thin wrapper over the
+ * registry for back-compat with existing call sites.
  */
 export function createAgentRunner(agentType: string): AgentRunner {
-  switch (agentType) {
-    case "claude":
-      return new ClaudeAgentRunner();
-    case "codex":
-      return new CodexAgentRunner();
-    case "dummy":
-      return new DummyAgentRunner();
-    case "mock":
-      return new MockAgentRunner(
-        "user-home/sessions/34681283-bf20-4dc4-8301-a0929104002e.jsonl",
-      );
-    default:
-      throw new Error(`Unknown agent type: ${agentType}`);
-  }
+  return createRunner(agentType);
 }
diff --git a/src/kernel/agents/index.ts b/src/kernel/agents/index.ts
index 47d38b8..9649c19 100644
--- a/src/kernel/agents/index.ts
+++ b/src/kernel/agents/index.ts
@@ -1 +1,4 @@
+export * from "./aliases";
 export * from "./factory";
+export * from "./registry";
+export * from "./runtime-default";
diff --git a/src/kernel/agents/registry.ts b/src/kernel/agents/registry.ts
new file mode 100644
index 0000000..153d0c4
--- /dev/null
+++ b/src/kernel/agents/registry.ts
@@ -0,0 +1,50 @@
+import { createLogger, type AgentRunner } from "@/shared";
+
+const _logger = createLogger("agent-registry");
+
+/**
+ * Factory that produces a fresh `AgentRunner` instance. Deferred so
+ * registration can happen at module-load time without paying the cost of
+ * constructing runners that are never used.
+ */
+type RunnerFactory = () => AgentRunner;
+
+const _runners = new Map<string, RunnerFactory>();
+
+/**
+ * Register a runner under a type name. Later registrations with the same
+ * type overwrite — useful for plugins that wrap/replace a built-in.
+ */
+export function registerRunner(type: string, factory: RunnerFactory): void {
+  const overwrite = _runners.has(type);
+  _runners.set(type, factory);
+  if (overwrite) {
+    _logger.info({ type }, "runner type re-registered (overwrite)");
+  } else {
+    _logger.info({ type }, "runner type registered");
+  }
+}
+
+/**
+ * Create a runner instance for the given type. Throws when no runner is
+ * registered under the name — the caller is expected to surface a clear
+ * error to the user (e.g. "check `agents.default.type` in config.yaml").
+ */
+export function createRunner(type: string): AgentRunner {
+  const factory = _runners.get(type);
+  if (!factory) {
+    const known = Array.from(_runners.keys()).join(", ") || "<none>";
+    throw new Error(
+      `Unknown agent runner type: \`${type}\`. Known types: ${known}.`,
+    );
+  }
+  return factory();
+}
+
+/**
+ * List currently-registered runner types. Intended for diagnostics /
+ * `/help`-style surfaces; order is insertion order.
+ */
+export function listRunnerTypes(): string[] {
+  return Array.from(_runners.keys());
+}
diff --git a/src/kernel/agents/runtime-default.ts b/src/kernel/agents/runtime-default.ts
new file mode 100644
index 0000000..6578c12
--- /dev/null
+++ b/src/kernel/agents/runtime-default.ts
@@ -0,0 +1,115 @@
+import { config } from "@/shared";
+
+import { listRunnerTypes } from "./registry";
+
+/**
+ * Runner types that stay registered for tests (DummyAgentRunner /
+ * MockAgentRunner) but must never appear in user-facing listings like
+ * `/setting` or `/agent list`. Filter with `filterUserFacingAgentTypes`.
+ * Selecting one by explicit name still works — this is display-only.
+ */
+const HIDDEN_AGENT_TYPES = new Set(["dummy", "mock"]);
+
+export function filterUserFacingAgentTypes(types: string[]): string[] {
+  return types.filter((t) => !HIDDEN_AGENT_TYPES.has(t));
+}
+
+let runtimeDefaultAgentType: string | null = null;
+
+export interface AgentRuntimeState {
+  activeType: string;
+  configuredDefaultType: string | null;
+  hasRuntimeOverride: boolean;
+  availableTypes: string[];
+}
+
+export interface SetRuntimeDefaultAgentResult {
+  previousType: string;
+  currentType: string;
+  changed: boolean;
+}
+
+/**
+ * Agent type used when creating a new session. Existing sessions keep the
+ * agent_type stored in the DB so runner-specific resume state is not mixed.
+ */
+export function getRuntimeDefaultAgentType(): string {
+  return runtimeDefaultAgentType ?? config.agents.default.type;
+}
+
+export function getAgentRuntimeState(): AgentRuntimeState {
+  const configuredDefaultType = _readConfiguredDefaultAgentType();
+  return {
+    activeType:
+      runtimeDefaultAgentType ??
+      configuredDefaultType ??
+      listRunnerTypes()[0] ??
+      "<none>",
+    configuredDefaultType,
+    hasRuntimeOverride: runtimeDefaultAgentType !== null,
+    availableTypes: listRunnerTypes(),
+  };
+}
+
+export function setRuntimeDefaultAgentType(
+  type: string,
+): SetRuntimeDefaultAgentResult {
+  const normalized = type.trim();
+  const availableTypes = listRunnerTypes();
+  const resolvedType = _resolveAvailableType(normalized, availableTypes);
+  if (!resolvedType) {
+    throw new UnknownAgentTypeError(normalized, availableTypes);
+  }
+  const previousType = getAgentRuntimeState().activeType;
+  runtimeDefaultAgentType = resolvedType;
+  return {
+    previousType,
+    currentType: resolvedType,
+    changed: previousType !== resolvedType,
+  };
+}
+
+export function resetRuntimeDefaultAgentType(): SetRuntimeDefaultAgentResult {
+  const configuredDefaultType = _readConfiguredDefaultAgentType();
+  if (!configuredDefaultType) {
+    throw new Error("config.yaml has not been loaded yet.");
+  }
+  const previousType = getAgentRuntimeState().activeType;
+  runtimeDefaultAgentType = null;
+  return {
+    previousType,
+    currentType: configuredDefaultType,
+    changed: previousType !== configuredDefaultType,
+  };
+}
+
+export class UnknownAgentTypeError extends Error {
+  constructor(
+    readonly type: string,
+    readonly availableTypes: string[],
+  ) {
+    super(
+      `Unknown agent type: ${type}. Available types: ${
+        availableTypes.join(", ") || "<none>"
+      }.`,
+    );
+    this.name = "UnknownAgentTypeError";
+  }
+}
+
+function _readConfiguredDefaultAgentType(): string | null {
+  try {
+    return config.agents.default.type;
+  } catch {
+    return null;
+  }
+}
+
+function _resolveAvailableType(
+  input: string,
+  availableTypes: string[],
+): string | null {
+  if (availableTypes.includes(input)) return input;
+  const lowered = input.toLowerCase();
+  return availableTypes.find((type) => type.toLowerCase() === lowered) ?? null;
+}
diff --git a/src/kernel/codex-resume-card.ts b/src/kernel/codex-resume-card.ts
new file mode 100644
index 0000000..8de7849
--- /dev/null
+++ b/src/kernel/codex-resume-card.ts
@@ -0,0 +1,105 @@
+import type {
+  ButtonElement,
+  Card,
+  ColumnSetElement,
+} from "@/community/feishu/messaging/types";
+
+import { buildCardIntro, buildMarkdown, buildResultCard } from "./setup/card-ui";
+
+export const CODEX_RESUME_RESTART_ACTION = "codex_resume_restart";
+
+export interface CodexResumeRestartValue {
+  action: typeof CODEX_RESUME_RESTART_ACTION;
+  [key: string]: unknown;
+}
+
+export function buildCodexResumeMissingCard(options: {
+  resumeId: string;
+}): Card {
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: {
+        content: "Codex 续接失败",
+      },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements: [
+        buildCardIntro({
+          title: "Codex 续接失败",
+          subtitle: "本地 Codex 找不到上一轮 rollout",
+        }),
+        buildMarkdown(
+          [
+            `- Thread ID：\`${options.resumeId}\``,
+            "- 原因：Codex 本地会话库里没有这个 rollout，可能是 `CODEX_HOME` 变化、会话文件被清理，或旧会话记录来自不同运行环境。",
+            "- 当前不会自动重开。确认可以丢弃 Codex CLI 的续跑状态后，再点击下面按钮。",
+          ].join("\n"),
+        ),
+        _buildRestartButtonRow(),
+      ],
+    },
+  };
+}
+
+export function buildCodexResumeRestartingCard(): Card {
+  return buildResultCard({
+    title: "Codex 续接恢复",
+    summary: "⏳ 正在重新开始 Codex 会话…",
+  });
+}
+
+export function buildCodexResumeRestartedCard(): Card {
+  return buildResultCard({
+    title: "Codex 续接恢复",
+    summary: "✅ 已重新开始 Codex 会话，新回复会在话题内继续生成。",
+  });
+}
+
+export function buildCodexResumeExpiredCard(): Card {
+  return buildResultCard({
+    title: "Codex 续接恢复",
+    summary: "⚠️  这张恢复卡片已失效，请重新发送消息触发恢复提示。",
+  });
+}
+
+export function formatCodexResumeMissingText(resumeId: string): string {
+  return [
+    "Codex 续接失败：本地 Codex 找不到上一轮 rollout。",
+    "",
+    `Thread ID：${resumeId}`,
+    "",
+    "当前不会自动重开。请在 Feishu 卡片上点击「重新开始 Codex 会话」，或手动开启新会话。",
+  ].join("\n");
+}
+
+function _buildRestartButtonRow(): ColumnSetElement {
+  const value: CodexResumeRestartValue = {
+    action: CODEX_RESUME_RESTART_ACTION,
+  };
+  const button: ButtonElement = {
+    tag: "button",
+    name: "codex_resume_restart",
+    text: { tag: "plain_text", content: "重新开始 Codex 会话" },
+    type: "primary",
+    width: "fill",
+    behaviors: [{ type: "callback", value }],
+  };
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    columns: [
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 1,
+        elements: [button],
+      },
+    ],
+  };
+}
diff --git a/src/kernel/commands/cards.ts b/src/kernel/commands/cards.ts
new file mode 100644
index 0000000..0daeaab
--- /dev/null
+++ b/src/kernel/commands/cards.ts
@@ -0,0 +1,50 @@
+import type { Card, Element } from "../../community/feishu/messaging/types";
+import {
+  buildCardIntro,
+  buildMarkdown,
+  buildSectionBlock,
+} from "../setup/card-ui";
+
+type CommandCardSection = {
+  title: string;
+  lines: string[];
+};
+
+export function buildCommandCard(options: {
+  title: string;
+  lines?: string[];
+  sections?: CommandCardSection[];
+  summary?: string;
+}): Card {
+  const elements: Element[] = [
+    buildCardIntro({ title: options.title }),
+  ];
+
+  if ((options.lines?.length ?? 0) > 0) {
+    elements.push(buildMarkdown(options.lines!.join("\n")));
+  }
+
+  for (const section of options.sections ?? []) {
+    elements.push(...buildSectionBlock({
+      title: section.title,
+      lines: section.lines,
+    }));
+  }
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: {
+        content: options.summary ?? options.title,
+      },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
diff --git a/src/kernel/commands/handlers.ts b/src/kernel/commands/handlers.ts
new file mode 100644
index 0000000..0ad09b8
--- /dev/null
+++ b/src/kernel/commands/handlers.ts
@@ -0,0 +1,943 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import {
+  filterUserFacingAgentTypes,
+  getAgentRuntimeState,
+  resetRuntimeDefaultAgentType,
+  setRuntimeDefaultAgentType,
+  UnknownAgentTypeError,
+} from "@/kernel/agents";
+import { formatRepoRef } from "@/kernel/repo-ref";
+import {
+  ensureCachedMirror,
+  formatAheadBehind,
+  listRepoSyncState,
+  readRepoHead,
+  syncWorkspace,
+  type RepoSyncResult,
+} from "@/kernel/workspaces";
+import { loadPredefinedRepos } from "@/shared";
+
+import type { Card, Element } from "../../community/feishu/messaging/types";
+import { buildMarkdown } from "../setup/card-ui";
+
+import { buildCommandCard } from "./cards";
+import type {
+  CardCommandResult,
+  CommandContext,
+  CommandHandler,
+} from "./types";
+
+/**
+ * Non-LLM commands that run inside `_handleInboundMessage` before the
+ * TaskDispatcher. All commands are scoped to the current Feishu `chat_id`
+ * unless noted. Missing `chat_id` means the message came from a source
+ * that doesn't support group bindings; we reject those commands politely.
+ *
+ * User-facing copy is intentionally in Chinese — these commands surface
+ * directly in Feishu group chats where the audience is Chinese-speaking.
+ */
+
+function requireChatId(ctx: CommandContext): string | null {
+  const chatId = ctx.message.chat_id;
+  if (!chatId) {
+    return null;
+  }
+  return chatId;
+}
+
+/**
+ * Gate for commands that may create a workspace or mutate repo state.
+ * P2P (`chat_type === "single"`) is intentionally kept read/reuse-only —
+ * it can browse via `/status` / `/ls` and rebind via `/switch`, but it
+ * shouldn't spawn new workspaces or kick off clones. Returns the chat_id
+ * when the command may proceed, or null when it should be rejected; the
+ * caller picks the right error copy.
+ */
+function requireGroupChat(ctx: CommandContext): string | null {
+  const chatId = ctx.message.chat_id;
+  if (!chatId) return null;
+  if (ctx.message.chat_type === "single") return null;
+  return chatId;
+}
+
+async function execGit(
+  args: string[],
+  cwd: string,
+): Promise<{ ok: boolean; stdout: string; stderr: string; code: number }> {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  return { ok: code === 0, stdout: stdout.trim(), stderr: stderr.trim(), code };
+}
+
+function cardReply(
+  title: string,
+  lines: string[],
+  options?: {
+    sections?: Array<{ title: string; lines: string[]; expanded?: boolean }>;
+    summary?: string;
+  },
+): CardCommandResult {
+  const fallbackLines = [title, ...lines];
+  for (const section of options?.sections ?? []) {
+    fallbackLines.push(section.title, ...section.lines);
+  }
+  return {
+    kind: "card",
+    card: buildCommandCard({
+      title,
+      lines,
+      sections: options?.sections,
+      summary: options?.summary,
+    }),
+    fallback_text: fallbackLines.join("\n"),
+  };
+}
+
+const AGENT_USAGE =
+  "用法：`/agent`、`/agent list`、`/agent use <type>`、`/agent reset`";
+
+function agentStatusReply(): CardCommandResult {
+  const state = getAgentRuntimeState();
+  const source = state.hasRuntimeOverride ? "运行时" : "配置";
+  const lines = [
+    `- 当前默认 Agent：\`${state.activeType}\`（${source}）`,
+    state.configuredDefaultType
+      ? `- 配置默认：\`${state.configuredDefaultType}\``
+      : "- 配置默认：(config.yaml 未加载)",
+    "- 影响范围：之后创建的新 session；已有 session 会继续使用创建时记录的 Agent。",
+  ];
+  const visibleTypes = filterUserFacingAgentTypes(state.availableTypes);
+  const agentLines =
+    visibleTypes.length > 0
+      ? visibleTypes.map((type) => {
+          const marks: string[] = [];
+          if (type === state.activeType) marks.push("当前");
+          if (type === state.configuredDefaultType) marks.push("配置默认");
+          return `- \`${type}\`${marks.length ? ` ← ${marks.join(" / ")}` : ""}`;
+        })
+      : ["- (当前没有注册任何 Agent runner)"];
+  return cardReply("Agent 管理", lines, {
+    sections: [{ title: "可选 Agent", lines: agentLines }],
+  });
+}
+
+const agentHandler: CommandHandler = {
+  name: "agent",
+  description: "/agent [list|use <type>|reset] — 查看或切换运行时默认 Agent",
+  async execute(ctx) {
+    const [verbRaw, typeRaw] = ctx.args;
+    const verb = verbRaw?.toLowerCase();
+    if (!verb || verb === "list" || verb === "status") {
+      return agentStatusReply();
+    }
+
+    if (verb === "reset" || verb === "default") {
+      const result = resetRuntimeDefaultAgentType();
+      return cardReply("Agent 管理", [
+        result.changed
+          ? `✅ 已恢复配置默认 Agent：\`${result.currentType}\``
+          : `ℹ️  当前已经是配置默认 Agent：\`${result.currentType}\``,
+      ]);
+    }
+
+    const requestedType =
+      verb === "use" || verb === "switch" || verb === "set"
+        ? typeRaw
+        : verbRaw;
+    if (!requestedType) {
+      return cardReply("Agent 管理", [
+        AGENT_USAGE,
+        "- 可先执行 `/agent list` 查看可选项。",
+      ]);
+    }
+
+    try {
+      const result = setRuntimeDefaultAgentType(requestedType);
+      ctx.logger.info(
+        {
+          previous_agent_type: result.previousType,
+          current_agent_type: result.currentType,
+        },
+        "runtime default agent switched",
+      );
+      return cardReply("Agent 管理", [
+        result.changed
+          ? `✅ 已切换运行时默认 Agent：\`${result.previousType}\` → \`${result.currentType}\``
+          : `ℹ️  当前默认 Agent 已经是 \`${result.currentType}\``,
+        "- 之后创建的新 session 会使用这个 Agent；已有 session 不会被强制切换。",
+      ]);
+    } catch (err) {
+      if (err instanceof UnknownAgentTypeError) {
+        return cardReply("Agent 管理", [
+          `❌ 未知 Agent：\`${err.type}\``,
+          AGENT_USAGE,
+        ], {
+          sections: [
+            {
+              title: "可选 Agent",
+              lines: err.availableTypes.map((type) => `- \`${type}\``),
+            },
+          ],
+        });
+      }
+      throw err;
+    }
+  },
+};
+
+const agentsHandler: CommandHandler = {
+  name: "agents",
+  description: "/agents — 查看可选 Agent 列表",
+  async execute() {
+    return agentStatusReply();
+  },
+};
+
+const bindHandler: CommandHandler = {
+  name: "bind",
+  description: "/bind [workspace-id] — 绑定当前群到一个 workspace；传 id 时复用已有空间",
+  async execute(ctx) {
+    const chatId = requireGroupChat(ctx);
+    if (!chatId) {
+      if (ctx.message.chat_type === "single") {
+        return "❌ /bind 仅在飞书群内可用；单聊请使用 `/switch` 挑选已有 workspace。";
+      }
+      return "❌ /bind 仅在飞书群内可用。";
+    }
+    const [workspaceId] = ctx.args;
+    if (workspaceId) {
+      const workspace = ctx.workspaceStore.getWorkspace(workspaceId);
+      if (!workspace) {
+        return `❌ workspace id \`${workspaceId}\` 不存在。先在已有群里执行 \`/status\` 或 \`/setup\` 获取正确的 id。`;
+      }
+      // Don't reset active_repo/active_branch here — they live on the
+      // workspace and are shared by every bound group. Inherit whatever the
+      // workspace already has.
+      const binding = ctx.workspaceStore.upsertBinding(chatId, {
+        workspace_id: workspaceId,
+      });
+      ctx.logger.info(
+        { chat_id: chatId, workspace_id: workspaceId, binding },
+        "group rebound to existing workspace",
+      );
+      const activeLine = binding.active_repo
+        ? `- 活跃仓库：\`${formatRepoRef(
+            binding.active_repo,
+            readRepoHead(join(binding.workspace_path, binding.active_repo)),
+          )}\``
+        : "- 活跃仓库：(未设置)";
+      return cardReply("绑定 Workspace", [
+        `✅ 当前群已绑定到 \`${binding.workspace_name}\``,
+        `- Workspace ID：\`${binding.workspace_id}\``,
+        activeLine,
+      ]);
+    }
+    const existing = ctx.workspaceStore.getBinding(chatId);
+    // Empty patch: just ensure the binding row + workspace dir exist; don't
+    // touch active_repo/active_branch (those are managed by /setup).
+    const binding = ctx.workspaceStore.upsertBinding(chatId, {});
+    ctx.logger.info({ chat_id: chatId, binding }, "group binding ensured");
+    if (existing) {
+      return cardReply("绑定 Workspace", [
+        `ℹ️  当前群已绑定 \`${binding.workspace_name}\``,
+        `- Workspace ID：\`${binding.workspace_id}\``,
+      ]);
+    }
+    return cardReply("绑定 Workspace", [
+      `✅ 已创建 \`${binding.workspace_name}\``,
+      `- Workspace ID：\`${binding.workspace_id}\``,
+      "- 下一步：`/setup`",
+    ]);
+  },
+};
+
+const unbindHandler: CommandHandler = {
+  name: "unbind",
+  description: "/unbind — 清除当前群的绑定（回退到默认 workspace）",
+  async execute(ctx) {
+    const chatId = requireGroupChat(ctx);
+    if (!chatId) {
+      if (ctx.message.chat_type === "single") {
+        return "❌ /unbind 仅在飞书群内可用；单聊请使用 `/switch` 并选择「取消绑定」。";
+      }
+      return "❌ /unbind 仅在飞书群内可用。";
+    }
+    const removed = ctx.workspaceStore.deleteBinding(chatId);
+    if (!removed) return cardReply("解绑 Workspace", ["ℹ️  当前群未绑定。"]);
+    return cardReply("解绑 Workspace", ["✅ 已清除群绑定。"]);
+  },
+};
+
+const statusHandler: CommandHandler = {
+  name: "status",
+  description: "/status — 查看当前群的绑定及已克隆的仓库",
+  async execute(ctx) {
+    const chatId = requireChatId(ctx);
+    if (!chatId) {
+      return cardReply("Workspace 状态", ["ℹ️  当前不在飞书会话上下文，使用默认 workspace。"]);
+    }
+    const resolution = ctx.workspaceStore.resolve(chatId);
+    const isP2P = ctx.message.chat_type === "single";
+    const lines: string[] = [];
+    if (!resolution.binding) {
+      lines.push(
+        isP2P
+          ? "ℹ️  当前单聊 **未绑定** 任何 workspace。"
+          : "ℹ️  当前群 **未绑定**。",
+      );
+      if (isP2P) {
+        lines.push("- 可用：`/switch`");
+      } else {
+        lines.push("- 可用：`/setup`  `/bind <workspace-id>`  `/switch`");
+      }
+      return cardReply("Workspace 状态", lines);
+    }
+    lines.push("**当前群绑定：**");
+    lines.push(`- Workspace ID：\`${resolution.binding.workspace_id}\``);
+    lines.push(`- Workspace 名称：\`${resolution.binding.workspace_name}\``);
+    const activeRepo = resolution.binding.active_repo;
+    const repoStates = listRepoSyncState(resolution.binding.workspace_path);
+    // Always read branch from on-disk HEAD, not the stored `active_branch`
+    // hint — the runner never force-checks-out, so "active" means "whatever
+    // the repo is currently on".
+    const activeState = activeRepo
+      ? repoStates.find((s) => s.name === activeRepo)
+      : undefined;
+    const activeLabel = activeRepo
+      ? `\`${formatRepoRef(activeRepo, activeState?.branch)}\``
+      : "(未设置)";
+    lines.push(`- 活跃仓库：${activeLabel}`);
+    if (repoStates.length > 0) {
+      const repoLines: string[] = [];
+      for (const s of repoStates) {
+        const primary = s.name === activeRepo ? " ← 活跃" : "";
+        const ahead_behind = formatAheadBehind(s.ahead, s.behind);
+        const dirty = s.dirty ? " •" : "";
+        const label = formatRepoRef(s.name, s.branch);
+        const suffix = ahead_behind ? ` ${ahead_behind}` : "";
+        repoLines.push(`- \`${label}\`${suffix}${dirty}${primary}`);
+      }
+      return cardReply("Workspace 状态", lines, {
+        sections: [{ title: "仓库", lines: repoLines }],
+      });
+    } else {
+      lines.push("- 仓库：0");
+    }
+    return cardReply("Workspace 状态", lines);
+  },
+};
+
+const syncHandler: CommandHandler = {
+  name: "sync",
+  description: "/sync — 对当前 workspace 下的每个仓库 fetch + 快进拉取",
+  async execute(ctx) {
+    const chatId = requireChatId(ctx);
+    const resolution = ctx.workspaceStore.resolve(chatId ?? null);
+    if (!resolution.binding && chatId) {
+      return "ℹ️  当前群未绑定 workspace；先执行 `/setup` 或 `/bind` 再 `/sync`。";
+    }
+    const workspacePath = resolution.binding?.workspace_path ?? resolution.cwd;
+    ctx.logger.info({ workspace_path: workspacePath }, "manual /sync requested");
+    const results = await syncWorkspace(workspacePath, { pull: true });
+    if (results.length === 0) {
+      return cardReply("同步结果", ["ℹ️  当前 workspace 下没有 git 仓库。"]);
+    }
+    return cardReply("同步结果", [], {
+      sections: [{ title: "仓库", lines: results.map(_formatSyncLine) }],
+    });
+  },
+};
+
+const lsHandler: CommandHandler = {
+  name: "ls",
+  description: "/ls — 列出当前群 workspace 下的所有仓库",
+  async execute(ctx) {
+    const chatId = requireChatId(ctx);
+    const resolution = ctx.workspaceStore.resolve(chatId ?? null);
+    const workspacePath = resolution.binding?.workspace_path ?? resolution.cwd;
+    const repos = listRepoBasenames(workspacePath);
+    if (repos.length === 0) {
+      return cardReply("仓库", ["ℹ️  当前 workspace 还没有仓库。"]);
+    }
+    const primary = resolution.binding?.active_repo;
+    const lines: string[] = [];
+    for (const name of repos) {
+      const mark = name === primary ? " ← 活跃" : "";
+      lines.push(`- \`${name}\`${mark}`);
+    }
+    return cardReply("仓库", [], {
+      sections: [{ title: "列表", lines }],
+    });
+  },
+};
+
+const cloneHandler: CommandHandler = {
+  name: "clone",
+  description: "/clone <git-url> [别名] — 将仓库克隆到当前群的 workspace",
+  async execute(ctx) {
+    const chatId = requireGroupChat(ctx);
+    if (!chatId) {
+      if (ctx.message.chat_type === "single") {
+        return "❌ /clone 仅在飞书群内可用；单聊请先 `/switch` 到目标 workspace，在群里执行克隆。";
+      }
+      return "❌ /clone 仅在飞书群内可用。";
+    }
+    const [url, explicitName] = ctx.args;
+    if (!url) return "用法：`/clone <git-url> [别名]`";
+    const resolution = ctx.workspaceStore.resolve(chatId);
+    const workspacePath = resolution.binding?.workspace_path ?? resolution.cwd;
+    // Ensure binding row exists so workspace_path is persisted even before active_repo is picked
+    if (!resolution.binding) {
+      ctx.workspaceStore.upsertBinding(chatId, {});
+    }
+    const name = explicitName || deriveRepoName(url);
+    const targetPath = join(workspacePath, name);
+    if (existsSync(targetPath)) {
+      return `❌ workspace 中已存在 \`${name}\`，请换个别名，或使用 \`/ls\` 查看已克隆的仓库。`;
+    }
+    // `git clone` can take a while, so we don't block the inbound handler on
+    // it. Show a "cloning…" card immediately and finish the clone in the
+    // background; the kernel patches the same card to done/failed via
+    // `deferred_card`. Cheap validation above still replies synchronously.
+    return {
+      kind: "deferred_card",
+      initial: buildCommandCard({
+        title: "克隆中",
+        lines: [`⏳ 正在克隆 \`${name}\`…`],
+      }),
+      fallback_text: `正在克隆 ${name}…`,
+      async run() {
+        // If this URL matches a predefined repo in REPOS.md, route the
+        // clone through the shared object cache so the history is fetched
+        // at most once across all workspaces. Arbitrary URLs still do a
+        // plain clone — maintaining a cache entry for a one-off repo
+        // isn't worth the bookkeeping.
+        const catalogMatch = _findPredefinedByUrl(url);
+        const mirror = catalogMatch
+          ? await ensureCachedMirror(catalogMatch)
+          : null;
+        const cloneArgs = mirror
+          ? ["clone", "--reference", mirror, url, name]
+          : ["clone", url, name];
+        ctx.logger.info(
+          { chat_id: chatId, url, name, using_cache: Boolean(mirror) },
+          "cloning repo",
+        );
+        const result = await execGit(cloneArgs, workspacePath);
+        if (!result.ok) {
+          return buildCommandCard({
+            title: "克隆失败",
+            lines: [
+              `❌ \`git clone\` 失败：`,
+              "```",
+              result.stderr || result.stdout,
+              "```",
+            ],
+          });
+        }
+        return buildCommandCard({
+          title: "克隆完成",
+          lines: [`✅ 已克隆 \`${name}\`.`],
+        });
+      },
+    };
+  },
+};
+
+const checkoutHandler: CommandHandler = {
+  name: "checkout",
+  description: "/checkout <分支> — 切换当前活跃仓库的分支",
+  async execute(ctx) {
+    const chatId = requireGroupChat(ctx);
+    if (!chatId) {
+      if (ctx.message.chat_type === "single") {
+        return "❌ /checkout 仅在飞书群内可用；单聊共享 workspace 的分支由群侧管理。";
+      }
+      return "❌ /checkout 仅在飞书群内可用。";
+    }
+    const [branch] = ctx.args;
+    if (!branch) return "用法：`/checkout <分支>`";
+    const resolution = ctx.workspaceStore.resolve(chatId);
+    if (!resolution.binding?.active_repo) {
+      return "❌ 当前群没有活跃仓库。请先执行 `/setup`。";
+    }
+    const repoPath = join(
+      resolution.binding.workspace_path,
+      resolution.binding.active_repo,
+    );
+    // Reject dirty tree so the user can't accidentally drop uncommitted work
+    const status = await execGit(["status", "--short"], repoPath);
+    if (status.stdout) {
+      return `❌ \`${resolution.binding.active_repo}\` 工作区有未提交改动，拒绝切换分支：\n\`\`\`\n${status.stdout}\n\`\`\``;
+    }
+    const result = await execGit(["checkout", branch], repoPath);
+    if (!result.ok) {
+      return `❌ \`git checkout ${branch}\` 失败：\n\`\`\`\n${result.stderr || result.stdout}\n\`\`\``;
+    }
+    ctx.workspaceStore.upsertBinding(chatId, { active_branch: branch });
+    return cardReply("切换分支", [
+      `✅ \`${resolution.binding.active_repo}\` 已切换到 \`${branch}\``,
+    ]);
+  },
+};
+
+const ungroupHandler: CommandHandler = {
+  name: "ungroup",
+  description:
+    "/ungroup [群名或 chat_id] — 解散机器人创建的群（群内无参=当前群；单聊须指定）",
+  async execute(ctx) {
+    if (!ctx.message.channel_id) {
+      return "❌ /ungroup 需要飞书会话上下文。";
+    }
+    const channel = ctx.feishuChannels.get(ctx.message.channel_id);
+    if (!channel) {
+      return "❌ 找不到对应的飞书 channel。";
+    }
+    const senderOpenId = ctx.message.sender_open_id;
+    if (!senderOpenId) {
+      return "❌ 无法识别发命令的用户。";
+    }
+    const isP2P = ctx.message.chat_type === "single";
+
+    // Decide which chat to dismiss.
+    let targetChatId: string;
+    let targetName: string;
+    if (isP2P) {
+      const query = ctx.args.join(" ").trim();
+      if (!query) {
+        return "用法：`/ungroup <群名或 chat_id>`（单聊内必须指定目标）";
+      }
+      const matches = channel.findBotGroupForCreator(query, senderOpenId);
+      if (matches.length === 0) {
+        return `❌ 没有找到你创建的群匹配 \`${query}\`。`;
+      }
+      if (matches.length > 1) {
+        const idList = matches
+          .map((m) => `- \`${m.chat_name}\` (\`${m.chat_id}\`)`)
+          .join("\n");
+        return `⚠️  有多个同名群，请用 chat_id 指定：\n${idList}`;
+      }
+      targetChatId = matches[0]!.chat_id;
+      targetName = matches[0]!.chat_name;
+    } else {
+      const chatId = ctx.message.chat_id;
+      if (!chatId) return "❌ 无法获取当前群 chat_id。";
+      const row = channel.findBotGroup(chatId);
+      if (!row) {
+        return "❌ 当前群不是机器人创建的，拒绝解散。";
+      }
+      if (row.creator_open_id !== senderOpenId) {
+        return "🚫 只有当初用 /group 建群的人才能解散它。";
+      }
+      targetChatId = row.chat_id;
+      targetName = row.chat_name;
+    }
+
+    try {
+      await channel.dismissChat(targetChatId);
+    } catch (err) {
+      ctx.logger.error(
+        { err, chat_id: targetChatId },
+        "dismissChat failed",
+      );
+      return `❌ 解散失败：${(err as Error).message}`;
+    }
+    channel.deleteBotGroupRecord(targetChatId);
+    return cardReply("解散群聊", [
+      `✅ 已解散 \`${targetName}\` (\`${targetChatId}\`)。`,
+    ]);
+  },
+};
+
+const allowHandler: CommandHandler = {
+  name: "allow",
+  description: "/allow @user1 @user2 ... — 把 @ 的人加到机器人白名单",
+  async execute(ctx) {
+    if (!ctx.message.channel_id) {
+      return "❌ /allow 需要飞书会话上下文。";
+    }
+    const channel = ctx.feishuChannels.get(ctx.message.channel_id);
+    if (!channel) {
+      return "❌ 找不到对应的飞书 channel。";
+    }
+    const senderOpenId = ctx.message.sender_open_id;
+    if (!senderOpenId) {
+      return "❌ 无法识别发命令的用户。";
+    }
+    const mentions = ctx.message.mentions ?? [];
+    // Self-mention doesn't count — adding yourself is a no-op since you
+    // clearly already passed the whitelist gate to get here.
+    const targets = Array.from(
+      new Set(
+        mentions
+          .map((m) => m.open_id)
+          .filter((id) => id && id !== senderOpenId),
+      ),
+    );
+    if (targets.length === 0) {
+      return "用法：`/allow @user1 @user2 ...`（至少 @ 一个人，不能 @ 自己）";
+    }
+    let added: string[];
+    try {
+      added = await channel.addToWhitelist(targets, senderOpenId);
+    } catch (err) {
+      ctx.logger.error({ err, targets }, "addToWhitelist failed");
+      return `❌ 写入白名单失败：${(err as Error).message}`;
+    }
+    if (added.length === 0) {
+      return "ℹ️  所有指定用户已在白名单里，无需更新。";
+    }
+    return cardReply("白名单已更新", [
+      `✅ 新增 ${added.length} 人到白名单：`,
+      ...added.map((id) => `- \`${id}\``),
+    ]);
+  },
+};
+
+/**
+ * Toggle "auto respond" on the current thread. Default (muted) is must-@:
+ * inside a bot-created thread the bot still requires @-mention to reply,
+ * so humans can use the same thread to discuss with each other without
+ * the bot jumping in. `/unmute` flips the thread into auto-respond mode;
+ * `/mute` restores the default.
+ */
+function buildMuteHandler(
+  name: "mute" | "unmute",
+  description: string,
+  enabled: boolean,
+): CommandHandler {
+  const verb = enabled ? "解除静音" : "静音";
+  const stateLine = enabled
+    ? "✅ 已取消静音：本话题内的消息无需 @ 机器人也会响应。"
+    : "✅ 已静音：本话题内需要 @ 机器人后才会响应。";
+  return {
+    name,
+    description,
+    async execute(ctx) {
+      if (ctx.message.chat_type !== "group") {
+        return `❌ /${name} 仅在群聊话题内可用（单聊本就不需要 @）。`;
+      }
+      const threadId = ctx.message.thread_id;
+      if (!threadId) {
+        return `❌ /${name} 需要在一个话题里执行；请在机器人发起的话题内回复此命令。`;
+      }
+      if (!ctx.message.channel_id) {
+        return `❌ /${name} 需要飞书会话上下文。`;
+      }
+      const channel = ctx.feishuChannels.get(ctx.message.channel_id);
+      if (!channel) {
+        return "❌ 找不到对应的飞书 channel。";
+      }
+      channel.setThreadAutoRespond(threadId, enabled, ctx.message.session_id);
+      ctx.logger.info(
+        {
+          thread_id: threadId,
+          session_id: ctx.message.session_id,
+          auto_respond: enabled,
+        },
+        "thread auto-respond toggled",
+      );
+      return cardReply(verb, [stateLine]);
+    },
+  };
+}
+
+const muteHandler = buildMuteHandler(
+  "mute",
+  "/mute — 关闭本话题的免 @ 自动响应（恢复默认：必须 @ 机器人）",
+  false,
+);
+
+const unmuteHandler = buildMuteHandler(
+  "unmute",
+  "/unmute — 开启本话题的免 @ 自动响应（机器人自动接话）",
+  true,
+);
+
+/**
+ * Surface the conversation-level identifiers for the current message:
+ * chat / thread / session / agent / runner_session_id, plus the thread's
+ * auto-respond flag. Read-only — purely for the user to copy IDs out when
+ * debugging routing issues or attaching from another tool.
+ */
+const topicHandler: CommandHandler = {
+  name: "topic",
+  description: "/topic — 查看当前话题/会话的标识信息（chat_id / thread_id / session_id 等）",
+  async execute(ctx) {
+    const msg = ctx.message;
+    const chatLabel = msg.chat_type
+      ? `${msg.chat_id ?? "(无)"} (${msg.chat_type === "group" ? "群聊" : "单聊"})`
+      : msg.chat_id ?? "(无)";
+    const lines = [
+      `- Session ID：\`${msg.session_id}\``,
+      `- Thread ID：${msg.thread_id ? `\`${msg.thread_id}\`` : "(不在话题内)"}`,
+      `- Chat ID：${msg.chat_id ? `\`${chatLabel}\`` : "(无飞书会话上下文)"}`,
+      `- Channel ID：${msg.channel_id ? `\`${msg.channel_id}\`` : "(无)"}`,
+    ];
+
+    const session = ctx.sessionManager.getSession(msg.session_id);
+    if (session) {
+      lines.push(`- Agent 类型：\`${session.agent_type}\``);
+      if (session.runner_session_id) {
+        lines.push(`- Runner Session ID：\`${session.runner_session_id}\``);
+      } else {
+        lines.push("- Runner Session ID：(尚未建立)");
+      }
+    } else {
+      lines.push("- 数据库尚无该 session 记录（消息刚到，未持久化）。");
+    }
+
+    if (msg.thread_id && msg.channel_id) {
+      const channel = ctx.feishuChannels.get(msg.channel_id);
+      const info = channel?.getThreadInfo(msg.thread_id);
+      if (info) {
+        lines.push(
+          `- 话题免 @：${info.auto_respond ? "✅ 开启（无需 @ 机器人）" : "❌ 关闭（默认，需 @ 机器人）"}`,
+        );
+      }
+    }
+
+    return cardReply("话题信息", lines);
+  },
+};
+
+/**
+ * Grouped `/help` card.
+ *
+ * A flat list of 15+ commands is noisy, so commands are bucketed by intent
+ * and rendered as plain bullet lists under a bold group heading. No intro
+ * text, no collapsible panels, no nested frames — just readable markdown.
+ */
+interface HelpCommand {
+  usage: string;
+  note: string;
+}
+interface HelpGroup {
+  title: string;
+  commands: HelpCommand[];
+}
+
+const HELP_GROUPS: HelpGroup[] = [
+  {
+    title: "🚀 常用",
+    commands: [
+      { usage: "/setting", note: "打开设置面板（全局配置 + workspace 管理）" },
+      { usage: "/new <消息>", note: "开启新会话 + 新话题（须在主群、非话题内）" },
+      { usage: "/stop", note: "取消当前 session 正在执行的任务" },
+      { usage: "/help", note: "显示本消息" },
+    ],
+  },
+  {
+    title: "📦 Workspace",
+    commands: [
+      { usage: "/status", note: "查看当前群的绑定及已克隆的仓库" },
+      { usage: "/ls", note: "列出当前群 workspace 下的所有仓库" },
+      { usage: "/setup", note: "打开 workspace 配置卡片（仅群聊）" },
+      { usage: "/switch", note: "打开 workspace 切换卡片（群聊 & 单聊）" },
+      { usage: "/bind [workspace-id]", note: "绑定当前群到一个 workspace" },
+      { usage: "/unbind", note: "清除当前群的绑定（回退到默认 workspace）" },
+      { usage: "/workspaces", note: "/setting 的快捷入口" },
+    ],
+  },
+  {
+    title: "🔀 仓库操作",
+    commands: [
+      { usage: "/sync", note: "对当前 workspace 下每个仓库 fetch + 快进拉取" },
+      { usage: "/clone <git-url> [别名]", note: "克隆仓库到当前群 workspace" },
+      { usage: "/checkout <分支>", note: "切换当前活跃仓库的分支" },
+      { usage: "/repos", note: "管理 REPOS.md 中的预设仓库目录" },
+    ],
+  },
+  {
+    title: "🤖 Agent",
+    commands: [
+      {
+        usage: "/agent [list|use <type>|reset]",
+        note: "查看或切换运行时默认 Agent",
+      },
+      { usage: "/agents", note: "查看可选 Agent 列表" },
+    ],
+  },
+  {
+    title: "👥 群 / 权限",
+    commands: [
+      {
+        usage: "/group <群名> @user...",
+        note: "机器人建群并自动 /setup（仅单聊）",
+      },
+      { usage: "/ungroup", note: "解散机器人创建的群" },
+      { usage: "/allow @user...", note: "把 @ 的人加到机器人白名单" },
+    ],
+  },
+  {
+    title: "🔕 话题响应",
+    commands: [
+      { usage: "/topic", note: "查看当前话题/会话的标识信息（chat_id / thread_id / session_id 等）" },
+      { usage: "/mute", note: "让当前话题不再自动响应 @ 提醒" },
+      { usage: "/unmute", note: "恢复当前话题的自动响应" },
+    ],
+  },
+];
+
+function _buildHelpCard(): Card {
+  const elements: Element[] = [];
+  for (const group of HELP_GROUPS) {
+    const lines = [
+      `**${group.title}**`,
+      ...group.commands.map((c) => `- ${c.usage} — ${c.note}`),
+    ].join("\n");
+    elements.push(buildMarkdown(lines));
+  }
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: "❓ 可用命令" },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
+
+function _buildHelpFallbackText(): string {
+  const lines: string[] = ["可用命令"];
+  for (const group of HELP_GROUPS) {
+    lines.push("", group.title);
+    for (const c of group.commands) {
+      lines.push(`- ${c.usage} — ${c.note}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export const helpHandler: CommandHandler = {
+  name: "help",
+  description: "/help — 显示所有可用命令",
+  async execute() {
+    const result: CardCommandResult = {
+      kind: "card",
+      card: _buildHelpCard(),
+      fallback_text: _buildHelpFallbackText(),
+    };
+    return result;
+  },
+};
+
+export const BUILTIN_COMMANDS: CommandHandler[] = [
+  agentHandler,
+  agentsHandler,
+  bindHandler,
+  unbindHandler,
+  statusHandler,
+  syncHandler,
+  lsHandler,
+  cloneHandler,
+  checkoutHandler,
+  ungroupHandler,
+  allowHandler,
+  muteHandler,
+  unmuteHandler,
+  topicHandler,
+];
+
+function _formatSyncLine(r: RepoSyncResult): string {
+  const label = `\`${formatRepoRef(r.name, r.branch)}\``;
+  const ab = formatAheadBehind(r.ahead, r.behind);
+  const abSuffix = ab ? ` ${ab}` : "";
+  switch (r.status) {
+    case "up_to_date":
+      return `- ✅ ${label}${abSuffix}`;
+    case "fast_forwarded":
+      return (
+        `- ⬇️ ${label} 已快进${abSuffix}` +
+        (r.before_sha && r.after_sha
+          ? `：${r.before_sha} → ${r.after_sha}`
+          : "")
+      );
+    case "no_upstream":
+      return `- ℹ️  ${label} 无 upstream`;
+    case "detached":
+      return `- ⚠️  ${r.name} 处于 detached HEAD${abSuffix}`;
+    case "skipped_dirty":
+      return `- 🚧 ${label}${abSuffix} 工作区有未提交改动，跳过拉取`;
+    case "skipped_diverged":
+      return `- 🚧 ${label}${abSuffix} 本地与 upstream 分叉，跳过快进拉取`;
+    case "fetch_failed":
+      return `- ❌ ${label} fetch 失败${r.detail ? `：${r.detail}` : ""}`;
+    case "pull_failed":
+      return `- ❌ ${label}${abSuffix} pull 失败${r.detail ? `：${r.detail}` : ""}`;
+  }
+}
+
+function listRepoBasenames(workspacePath: string): string[] {
+  if (!existsSync(workspacePath)) return [];
+  try {
+    return readdirSync(workspacePath)
+      .filter((name) => !name.startsWith("."))
+      .filter((name) => {
+        const p = join(workspacePath, name);
+        try {
+          return statSync(p).isDirectory() && existsSync(join(p, ".git"));
+        } catch {
+          return false;
+        }
+      })
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function deriveRepoName(url: string): string {
+  let tail = url.trim();
+  if (tail.endsWith("/")) tail = tail.slice(0, -1);
+  const last = basename(tail);
+  return last.endsWith(".git") ? last.slice(0, -4) : last;
+}
+
+/**
+ * Look up a predefined repo by its git URL, normalizing trailing `.git`
+ * and `/` so users copy-pasting the URL without the `.git` suffix still
+ * hit the cache. Returns `null` when the URL isn't in REPOS.md.
+ */
+function _findPredefinedByUrl(
+  url: string,
+): { name: string; git_url: string } | null {
+  const norm = _normalizeGitUrl(url);
+  for (const repo of loadPredefinedRepos()) {
+    if (_normalizeGitUrl(repo.git_url) === norm) return repo;
+  }
+  return null;
+}
+
+function _normalizeGitUrl(url: string): string {
+  let u = url.trim().toLowerCase();
+  // Drop the scheme (https://, http://, ssh://, git://) so the same repo
+  // reached over different protocols normalizes to the same key.
+  u = u.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+  // Drop userinfo such as the "git@" in "git@host:group/repo".
+  u = u.replace(/^[^@/]+@/, "");
+  // scp-style "host:group/repo" -> "host/group/repo". The negative lookahead
+  // leaves a real "host:port" alone (port = digits followed by "/" or end).
+  u = u.replace(/^([^/:]+):(?!\d+(?:\/|$))/, "$1/");
+  // Drop an explicit port: "host:1234/path" -> "host/path".
+  u = u.replace(/^([^/:]+):\d+\//, "$1/");
+  if (u.endsWith("/")) u = u.slice(0, -1);
+  if (u.endsWith(".git")) u = u.slice(0, -4);
+  return u;
+}
diff --git a/src/kernel/commands/index.ts b/src/kernel/commands/index.ts
new file mode 100644
index 0000000..6c7b7ec
--- /dev/null
+++ b/src/kernel/commands/index.ts
@@ -0,0 +1,7 @@
+export * from "./parser";
+export * from "./registry";
+export * from "./types";
+export * from "./new-command";
+export * from "./passthrough";
+export * from "./unknown-command";
+export { BUILTIN_COMMANDS, helpHandler } from "./handlers";
diff --git a/src/kernel/commands/new-command.ts b/src/kernel/commands/new-command.ts
new file mode 100644
index 0000000..c67b01e
--- /dev/null
+++ b/src/kernel/commands/new-command.ts
@@ -0,0 +1,82 @@
+import type { UserMessage } from "@/shared";
+
+import type { Card } from "../../community/feishu/messaging/types";
+
+import { buildCommandCard } from "./cards";
+
+/**
+ * Helpers for the kernel-owned `/new` command. Extracted from `Kernel`
+ * so the parsing, message rewriting, and card construction can be unit
+ * tested without instantiating the full kernel graph.
+ */
+
+const NEW_COMMAND_PREFIX_WITH_SPACE = "/new ";
+
+/**
+ * Whether the given inbound text is a `/new` invocation (with or
+ * without arguments).
+ */
+export function isNewCommand(text: string): boolean {
+  return text === "/new" || text.startsWith(NEW_COMMAND_PREFIX_WITH_SPACE);
+}
+
+/**
+ * Extract the prompt that follows `/new `. Returns an empty string
+ * for bare `/new` or whitespace-only args — callers should surface
+ * the usage card in that case.
+ */
+export function extractNewPrompt(text: string): string {
+  if (!isNewCommand(text)) return "";
+  if (text === "/new") return "";
+  return text.slice(NEW_COMMAND_PREFIX_WITH_SPACE.length).trim();
+}
+
+/**
+ * Rewrite an inbound user message as the first turn of a brand-new
+ * session in a brand-new Feishu thread. Drops `thread_id` so the
+ * subsequent `replyMessage(replyInThread:true)` creates a fresh
+ * thread instead of landing inside the thread the `/new` was typed
+ * from; replaces `content` with just the prompt so the agent doesn't
+ * see the `/new` wrapper.
+ */
+export function createFreshUserMessage(
+  original: UserMessage,
+  prompt: string,
+  sessionId: string,
+): UserMessage {
+  return {
+    ...original,
+    session_id: sessionId,
+    thread_id: undefined,
+    content: [{ type: "text", text: prompt }],
+  };
+}
+
+export interface KernelCommandReply {
+  text: string;
+  card: Card;
+}
+
+export function buildNewCommandRejectionReply(): KernelCommandReply {
+  const lines = [
+    "❌ /new 需要在主群里使用。",
+    "- 当前已在话题中，飞书话题不支持嵌套。",
+    "- 请回到主群再执行 `/new <消息>`。",
+  ];
+  return {
+    text: "❌ /new 需要在主群（非话题内）使用；当前已在话题里，无法再嵌套新建。",
+    card: buildCommandCard({ title: "新会话", lines }),
+  };
+}
+
+export function buildNewCommandUsageReply(): KernelCommandReply {
+  const lines = [
+    "用法：`/new <消息>`",
+    "- 等价于在群里 @bot 开启一个新会话 + 新话题。",
+    "- 斜杠后的内容会作为第一条发给 agent 的消息。",
+  ];
+  return {
+    text: "用法：/new <消息>",
+    card: buildCommandCard({ title: "新会话", lines }),
+  };
+}
diff --git a/src/kernel/commands/parser.ts b/src/kernel/commands/parser.ts
new file mode 100644
index 0000000..a258787
--- /dev/null
+++ b/src/kernel/commands/parser.ts
@@ -0,0 +1,23 @@
+import type { ParsedCommand } from "./types";
+
+/**
+ * Parse a message body into a slash command. Returns null when the text
+ * doesn't start with `/` or is a single slash. Command name is normalized
+ * to lowercase; args are split on whitespace runs.
+ *
+ * Note: `/stop` is reserved for the kernel's task-cancel path and is
+ * handled before this parser is consulted.
+ */
+export function parseCommand(text: string): ParsedCommand | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/") || trimmed.length < 2) return null;
+  const body = trimmed.slice(1);
+  const parts = body.split(/\s+/);
+  const name = parts[0]?.toLowerCase();
+  if (!name) return null;
+  return {
+    name,
+    args: parts.slice(1),
+    raw: trimmed,
+  };
+}
diff --git a/src/kernel/commands/passthrough.ts b/src/kernel/commands/passthrough.ts
new file mode 100644
index 0000000..cd4f46d
--- /dev/null
+++ b/src/kernel/commands/passthrough.ts
@@ -0,0 +1,21 @@
+/**
+ * Slash commands that are NOT handled by the gateway but are still
+ * forwarded verbatim to the underlying agent CLI (Claude Code) instead of
+ * being rejected as unknown. These are commands the CLI owns and can act
+ * on in non-interactive `--print` / `--resume` mode.
+ *
+ * Everything outside this set that isn't a registered gateway/kernel
+ * command falls back to the "unknown command" reply — passing arbitrary
+ * `/typo` text to the LLM wastes a turn.
+ *
+ * Names are stored lowercase (matching {@link parseCommand}'s output).
+ */
+const PASSTHROUGH_COMMANDS = new Set<string>(["compact"]);
+
+/**
+ * Whether a parsed command name should be passed through to the agent.
+ * @param name - Lowercase command name (no leading slash).
+ */
+export function isPassthroughCommand(name: string): boolean {
+  return PASSTHROUGH_COMMANDS.has(name.toLowerCase());
+}
diff --git a/src/kernel/commands/registry.ts b/src/kernel/commands/registry.ts
new file mode 100644
index 0000000..1352661
--- /dev/null
+++ b/src/kernel/commands/registry.ts
@@ -0,0 +1,26 @@
+import { BUILTIN_COMMANDS, helpHandler } from "./handlers";
+import type { CommandHandler } from "./types";
+
+
+/**
+ * In-memory registry of slash commands. Kernel looks up by `name.toLowerCase()`
+ * and dispatches. Single instance per kernel; no dynamic registration for v1.
+ */
+export class CommandRegistry {
+  private readonly _map = new Map<string, CommandHandler>();
+
+  constructor(handlers: CommandHandler[] = BUILTIN_COMMANDS) {
+    for (const handler of handlers) {
+      this._map.set(handler.name.toLowerCase(), handler);
+    }
+    this._map.set(helpHandler.name, helpHandler);
+  }
+
+  get(name: string): CommandHandler | undefined {
+    return this._map.get(name.toLowerCase());
+  }
+
+  list(): CommandHandler[] {
+    return Array.from(this._map.values());
+  }
+}
diff --git a/src/kernel/commands/types.ts b/src/kernel/commands/types.ts
new file mode 100644
index 0000000..cadbf8d
--- /dev/null
+++ b/src/kernel/commands/types.ts
@@ -0,0 +1,78 @@
+import type { Logger, UserMessage } from "@/shared";
+
+import type { FeishuMessageChannel } from "../../community/feishu/messaging/message-channel";
+import type { Card } from "../../community/feishu/messaging/types";
+import type { SessionManager } from "../sessioning";
+import type { GroupWorkspaceStore } from "../workspaces";
+
+/**
+ * Parsed slash command from an inbound message.
+ * `name` is lowercase; `args` is whitespace-split and preserves order.
+ */
+export interface ParsedCommand {
+  name: string;
+  args: string[];
+  raw: string;
+}
+
+/** Execution context passed to a command handler. */
+export interface CommandContext {
+  message: UserMessage;
+  args: string[];
+  raw: string;
+  workspaceStore: GroupWorkspaceStore;
+  /**
+   * All active Feishu channels, keyed by id. Handlers that need to call SDK
+   * methods (e.g. `/ungroup` deleting a chat, `/allow` mutating the
+   * whitelist) look up the originating channel via `message.channel_id`.
+   */
+  feishuChannels: Map<string, FeishuMessageChannel>;
+  /**
+   * Read-only access to persisted session metadata, used by introspection
+   * commands (e.g. `/topic`) to surface agent_type / runner_session_id.
+   */
+  sessionManager: SessionManager;
+  logger: Logger;
+}
+
+export interface CardCommandResult {
+  kind: "card";
+  card: Card;
+  fallback_text: string;
+}
+
+/**
+ * Result for commands whose real work is slow (e.g. `/clone` running
+ * `git clone`). The kernel posts `initial` immediately as a "pending" card,
+ * then runs `run()` in the background and patches the SAME message with the
+ * returned card (pending → done/failed). Any error thrown by `run()` is
+ * caught by the kernel and rendered as a failure card, so a slow command can
+ * never crash the process or leave the user staring at a stuck card.
+ */
+export interface DeferredCardCommandResult {
+  kind: "deferred_card";
+  /** Card shown right away, before the slow work starts. */
+  initial: Card;
+  /** Plain-text fallback used when the channel cannot render cards. */
+  fallback_text: string;
+  /** Background work; resolves to the final card used to patch the message. */
+  run(): Promise<Card>;
+}
+
+export type CommandResult =
+  | string
+  | CardCommandResult
+  | DeferredCardCommandResult;
+
+/** A gateway-level command that bypasses the LLM entirely. */
+export interface CommandHandler {
+  /** Command name without the leading slash (lowercase). */
+  readonly name: string;
+  /** One-line help text shown by `/help`. */
+  readonly description: string;
+  /** Run the command; return reply text that will be sent to the chat. */
+  execute(
+    // eslint-disable-next-line no-unused-vars
+    ctx: CommandContext,
+  ): Promise<CommandResult>;
+}
diff --git a/src/kernel/commands/unknown-command.ts b/src/kernel/commands/unknown-command.ts
new file mode 100644
index 0000000..b878ee2
--- /dev/null
+++ b/src/kernel/commands/unknown-command.ts
@@ -0,0 +1,26 @@
+import { buildCommandCard } from "./cards";
+import type { KernelCommandReply } from "./new-command";
+import { parseCommand } from "./parser";
+
+/**
+ * Build the "unknown command" reply for `/`-prefixed messages that
+ * don't map to any registered handler. Kernel uses this as the
+ * fallback so unrecognized slashes fail loudly instead of being
+ * forwarded to the agent.
+ */
+export function buildUnknownCommandReply(text: string): KernelCommandReply {
+  const parsed = parseCommand(text);
+  const lines = parsed
+    ? [
+        `❌ \`/${parsed.name}\` 不是已注册的命令。`,
+        "- 使用 `/help` 查看所有可用命令。",
+      ]
+    : [
+        "❌ 命令格式不正确（斜杠后需要跟命令名）。",
+        "- 使用 `/help` 查看所有可用命令。",
+      ];
+  return {
+    text: lines.join("\n"),
+    card: buildCommandCard({ title: "未知命令", lines }),
+  };
+}
diff --git a/src/kernel/group/group-flow.ts b/src/kernel/group/group-flow.ts
new file mode 100644
index 0000000..db00530
--- /dev/null
+++ b/src/kernel/group/group-flow.ts
@@ -0,0 +1,250 @@
+import type { DrizzleDB } from "@/data";
+import type { Logger } from "@/shared";
+import { createLogger, uuid, type UserMessage } from "@/shared";
+
+import { feishuBotGroups } from "../../community/feishu/messaging/data";
+import type { FeishuMessageChannel } from "../../community/feishu/messaging/message-channel";
+import type { SetupFlow } from "../setup/setup-flow";
+
+/**
+ * Orchestrates the `/group <name> @user1 @user2` command.
+ *
+ * Flow:
+ * 1. Validate P2P-only + at least one @-mention.
+ * 2. Create a group via Feishu API with the sender + mentioned users.
+ * 3. Transfer ownership from the bot to the sender.
+ * 4. Persist the chat to `feishu_bot_groups` so `/ungroup` can look it up.
+ * 5. Post a welcome line in the new group and anchor an auto-triggered
+ *    `/setup` card to it (so the new group is initialized for a workspace).
+ * 6. Confirm back to the P2P sender.
+ *
+ * One-shot: no pending state is tracked on the instance — all lookup data
+ * lives in the DB.
+ */
+export class GroupFlow {
+  private readonly _logger: Logger = createLogger("group-flow");
+  private readonly _feishuChannels: Map<string, FeishuMessageChannel>;
+  private readonly _setupFlow: SetupFlow;
+  private readonly _db: DrizzleDB;
+
+  constructor(deps: {
+    feishuChannels: Map<string, FeishuMessageChannel>;
+    setupFlow: SetupFlow;
+    db: DrizzleDB;
+  }) {
+    this._feishuChannels = deps.feishuChannels;
+    this._setupFlow = deps.setupFlow;
+    this._db = deps.db;
+  }
+
+  async start(message: UserMessage): Promise<void> {
+    if (message.chat_type !== "single") {
+      await this._replyText(
+        message,
+        "❌ /group 仅在与机器人的单聊中可用。",
+      );
+      return;
+    }
+    if (!message.channel_id || !message.chat_id) {
+      await this._replyText(message, "❌ /group 缺少会话上下文。");
+      return;
+    }
+    const senderOpenId = message.sender_open_id;
+    if (!senderOpenId) {
+      await this._replyText(
+        message,
+        "❌ 无法识别发命令的用户，请稍后重试。",
+      );
+      return;
+    }
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) {
+      await this._replyText(message, "❌ 无法找到对应的飞书 channel。");
+      return;
+    }
+
+    const parsed = this._parseArgs(message, senderOpenId, channel.botOpenId);
+    if ("error" in parsed) {
+      await this._replyText(message, parsed.error);
+      return;
+    }
+    const { name, memberOpenIds } = parsed;
+
+    // The sender must be in the chat to become the owner; dedup in case
+    // they also @'d themselves. The bot is always auto-added by Feishu as
+    // the creator, no need to include it here.
+    const allMembers = Array.from(new Set([senderOpenId, ...memberOpenIds]));
+
+    let chatId: string;
+    try {
+      chatId = await channel.createChat({
+        name,
+        memberOpenIds: allMembers,
+      });
+    } catch (err) {
+      this._logger.error(
+        { err, name, members: allMembers },
+        "createChat failed",
+      );
+      await this._replyText(
+        message,
+        `❌ 建群失败：${(err as Error).message}`,
+      );
+      return;
+    }
+
+    try {
+      await channel.transferChatOwner(chatId, senderOpenId);
+    } catch (err) {
+      // Non-fatal: the group exists and members are in. Warn the user so
+      // they know the bot is still owner and can transfer manually.
+      this._logger.error(
+        { err, chat_id: chatId, new_owner: senderOpenId },
+        "transferChatOwner failed",
+      );
+      await this._replyText(
+        message,
+        `⚠️  群已建（\`${chatId}\`），但群主转让失败：${
+          (err as Error).message
+        }。机器人仍是群主，可稍后手动转让。`,
+      );
+    }
+
+    this._db
+      .insert(feishuBotGroups)
+      .values({
+        chat_id: chatId,
+        channel_id: channel.id,
+        chat_name: name,
+        creator_open_id: senderOpenId,
+        created_at: Date.now(),
+      })
+      .onConflictDoNothing()
+      .run();
+
+    // Post a welcome line first so `/setup` has a real message_id to anchor
+    // its card reply to — SetupFlow.start reuses message.id as `replyTo`.
+    let welcomeMessageId: string;
+    try {
+      welcomeMessageId = await channel.sendPlainText(
+        chatId,
+        "✅ 群已建好，下面请填写 /setup 卡片初始化 workspace。",
+      );
+    } catch (err) {
+      this._logger.error(
+        { err, chat_id: chatId },
+        "sendPlainText failed; skipping auto-setup",
+      );
+      await this._replyText(
+        message,
+        `✅ 已建群 \`${name}\` (\`${chatId}\`)，但自动发 /setup 卡片失败：${
+          (err as Error).message
+        }。请在群里 @ 机器人发 \`/setup\` 继续。`,
+      );
+      return;
+    }
+
+    const synthetic: UserMessage = {
+      id: welcomeMessageId,
+      session_id: uuid(),
+      role: "user",
+      channel_id: channel.id,
+      chat_id: chatId,
+      chat_type: "group",
+      sender_open_id: senderOpenId,
+      content: [{ type: "text", text: "" }],
+    };
+    try {
+      await this._setupFlow.start(synthetic);
+    } catch (err) {
+      this._logger.error(
+        { err, chat_id: chatId },
+        "auto /setup failed",
+      );
+      await this._replyText(
+        message,
+        `✅ 已建群 \`${name}\`，但自动 /setup 失败：${
+          (err as Error).message
+        }。请在群里 @ 机器人发 \`/setup\` 继续。`,
+      );
+      return;
+    }
+
+    await this._replyText(
+      message,
+      `✅ 已建群 \`${name}\`（${
+        allMembers.length
+      } 人），并在群里发出 /setup 卡片。`,
+    );
+  }
+
+  private _parseArgs(
+    message: UserMessage,
+    senderOpenId: string,
+    botOpenId: string | undefined,
+  ):
+    | { name: string; memberOpenIds: string[] }
+    | { error: string } {
+    // Empty mention list is fine: a bot + sender 2-person group is a valid
+    // Feishu chat and the primary way `/group` is used when the user only
+    // wants a workspace-bound chat for themselves.
+    const mentions = message.mentions ?? [];
+    const seen = new Set<string>();
+    const memberOpenIds: string[] = [];
+    for (const m of mentions) {
+      // Skip self — `/group` is issued by the sender, they're always in the
+      // new chat. Skip the bot too — Feishu auto-adds the creator, and
+      // we don't want `@bot /group …` to inflate the member count.
+      if (m.open_id === senderOpenId) continue;
+      if (botOpenId && m.open_id === botOpenId) continue;
+      if (seen.has(m.open_id)) continue;
+      seen.add(m.open_id);
+      memberOpenIds.push(m.open_id);
+    }
+
+    // Name is everything between `/group ` and the first mention placeholder.
+    // Use the message's text content verbatim — mentions carry `key`
+    // substrings (e.g. `@_user_0`) so we can split on the earliest one.
+    const text = message.content
+      .filter((c): c is { type: "text"; text: string } => c.type === "text")
+      .map((c) => c.text)
+      .join(" ")
+      .trim();
+    const stripped = text.replace(/^\/group\b/, "").trim();
+    let earliestIdx = stripped.length;
+    for (const m of mentions) {
+      if (!m.key) continue;
+      const idx = stripped.indexOf(m.key);
+      if (idx >= 0 && idx < earliestIdx) earliestIdx = idx;
+    }
+    const rawName = stripped.slice(0, earliestIdx).trim();
+    if (!rawName) {
+      return {
+        error: "❌ 群名不能为空。用法：`/group <群名> @user1 ...`",
+      };
+    }
+    return { name: rawName, memberOpenIds };
+  }
+
+  private async _replyText(
+    message: UserMessage,
+    text: string,
+  ): Promise<void> {
+    if (!message.channel_id) return;
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) return;
+    try {
+      await channel.replyMessage(
+        message.id,
+        {
+          role: "assistant",
+          session_id: message.session_id,
+          content: [{ type: "text", text }],
+        },
+        { streaming: false, replyInThread: false },
+      );
+    } catch (err) {
+      this._logger.warn({ err }, "group-flow _replyText failed");
+    }
+  }
+}
diff --git a/src/kernel/kernel.ts b/src/kernel/kernel.ts
index fca8da1..a07d2b0 100644
--- a/src/kernel/kernel.ts
+++ b/src/kernel/kernel.ts
@@ -1,7 +1,22 @@
+import {
+  contextLimitForModel,
+  getClaudeUsageCached,
+} from "@/community/anthropic";
 import { FeishuMessageChannel } from "@/community/feishu";
 import * as feishuMessagingSchema from "@/community/feishu/messaging/data";
+import type { Card } from "@/community/feishu/messaging/types";
+import { CodexMissingResumeError } from "@/community/openai";
 import { DataConnection } from "@/data";
-import type { AssistantMessage, UserMessage } from "@/shared";
+// Side-effect import: every module under `src/plugins/*` registers its
+// runner with the registry at load time. This must happen before any
+// session dispatch so `agents.default.type` can resolve plugin types.
+import "@/plugins";
+import type {
+  AssistantMessage,
+  CardActionPayload,
+  CardFooterStats,
+  UserMessage,
+} from "@/shared";
 import {
   config,
   createLogger,
@@ -13,11 +28,45 @@ import {
 
 import { HonoServer } from "../server";
 
+import {
+  buildAgentCancelledContent,
+  buildAgentFailureContent,
+} from "./agent-failure";
+import {
+  buildCodexResumeExpiredCard,
+  buildCodexResumeMissingCard,
+  buildCodexResumeRestartedCard,
+  buildCodexResumeRestartingCard,
+  CODEX_RESUME_RESTART_ACTION,
+  formatCodexResumeMissingText,
+} from "./codex-resume-card";
+import {
+  buildNewCommandRejectionReply,
+  buildNewCommandUsageReply,
+  buildUnknownCommandReply,
+  CommandRegistry,
+  isPassthroughCommand,
+  createFreshUserMessage,
+  extractNewPrompt,
+  isNewCommand,
+  parseCommand,
+  type CardCommandResult,
+  type DeferredCardCommandResult,
+} from "./commands";
+import { buildCommandCard } from "./commands/cards";
+import { GroupFlow } from "./group/group-flow";
 import { MultiChannelMessageGateway } from "./messaging";
+import { PERMISSION_ACTION, PermissionFlow, QUESTION_ACTION } from "./permission";
+import { ReposFlow } from "./repos";
 import { SessionManager } from "./sessioning";
 import * as sessioningSchema from "./sessioning/data";
+import { SettingFlow } from "./setting/setting-flow";
+import { SETUP_DISMISS_ACTION } from "./setup/setup-card";
+import { SetupFlow } from "./setup/setup-flow";
+import { SwitchFlow } from "./setup/switch-flow";
 import { TaskDispatcher } from "./tasking";
 import * as taskingSchema from "./tasking/data";
+import { GroupWorkspaceStore, syncWorkspace } from "./workspaces";
 
 /**
  * The kernel is the main entry point for the agentara application.
@@ -30,12 +79,34 @@ class Kernel {
   private _taskDispatcher!: TaskDispatcher;
   private _messageGateway!: MultiChannelMessageGateway;
   private _honoServer!: HonoServer;
+  private _workspaceStore!: GroupWorkspaceStore;
+  private _commandRegistry!: CommandRegistry;
+  private _feishuChannels = new Map<string, FeishuMessageChannel>();
+  private _setupFlow!: SetupFlow;
+  private _switchFlow!: SwitchFlow;
+  private _settingFlow!: SettingFlow;
+  private _reposFlow!: ReposFlow;
+  private _groupFlow!: GroupFlow;
+  private _permissionFlow!: PermissionFlow;
+  private _codexResumeRestarts = new Map<
+    string,
+    { sessionId: string; message: UserMessage }
+  >();
+  private _shuttingDown = false;
 
   constructor() {
     this._initDatabase();
     this._initSessionManager();
+    this._initWorkspaceStore();
+    this._initCommandRegistry();
     this._initTaskDispatcher();
     this._initMessageGateway();
+    this._initSetupFlow();
+    this._initSwitchFlow();
+    this._initSettingFlow();
+    this._initReposFlow();
+    this._initGroupFlow();
+    this._initPermissionFlow();
     this._initServer();
   }
 
@@ -59,6 +130,10 @@ class Kernel {
     return this._honoServer;
   }
 
+  get permissionFlow(): PermissionFlow {
+    return this._permissionFlow;
+  }
+
   private _initDatabase(): void {
     this._database = new DataConnection({
       ...taskingSchema,
@@ -71,6 +146,15 @@ class Kernel {
     this._sessionManager = new SessionManager(this._database.db);
   }
 
+  private _initWorkspaceStore(): void {
+    this._workspaceStore = new GroupWorkspaceStore(this._database.db);
+    this._workspaceStore.ensureBaseDirs();
+  }
+
+  private _initCommandRegistry(): void {
+    this._commandRegistry = new CommandRegistry();
+  }
+
   private _initServer(): void {
     this._honoServer = new HonoServer();
   }
@@ -89,20 +173,99 @@ class Kernel {
   private _initMessageGateway(): void {
     this._messageGateway = new MultiChannelMessageGateway(this._database.db);
     for (const channel of config.messaging.channels) {
-      this._messageGateway.registerChannel(
-        new FeishuMessageChannel(
-          channel.id,
-          {
-            chatId: channel.params.chat_id!,
-            appId: channel.params.app_id!,
-            appSecret: channel.params.app_secret!,
-          },
-          this._database.db,
-        ),
+      const splitCsv = (raw: string | undefined) =>
+        (raw ?? "")
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean);
+      const allowedOpenIds = splitCsv(channel.params.allowed_user_ids);
+      const allowedEmails = splitCsv(channel.params.allowed_user_emails);
+      const requireMention =
+        (channel.params.require_mention ?? "").toLowerCase() === "true";
+      const feishuChannel = new FeishuMessageChannel(
+        channel.id,
+        {
+          chatId: channel.params.chat_id!,
+          appId: channel.params.app_id!,
+          appSecret: channel.params.app_secret!,
+          requireMention,
+          allowedUserOpenIds:
+            allowedOpenIds.length > 0 ? allowedOpenIds : undefined,
+          allowedUserEmails:
+            allowedEmails.length > 0 ? allowedEmails : undefined,
+          // Uploads and quoted-resource downloads land inside the workspace
+          // the chat is currently bound to, so each chat's artifacts stay
+          // co-located with its session instead of piling up in a shared
+          // `$AGENTARA_HOME/workspace/uploads` pool.
+          resolveWorkspaceCwd: (chatId) =>
+            this._workspaceStore.resolve(chatId).cwd,
+          // Outbound relative paths (agent-generated file/image links) are
+          // relative to the cwd the agent actually ran in. A single channel
+          // serves many chats, so resolve from the owning session, not the
+          // channel's configured chat.
+          resolveSessionCwd: (sessionId) =>
+            this._sessionManager.getSession(sessionId)?.cwd,
+        },
+        this._database.db,
       );
+      this._feishuChannels.set(channel.id, feishuChannel);
+      this._messageGateway.registerChannel(feishuChannel);
     }
-    this._messageGateway.on("message:inbound", this._handleInboundMessage);
+    // `.on` discards the listener's returned promise, so any rejection that
+    // escapes an async handler becomes an unhandled rejection (which crashes
+    // the process). Guard the handler we drive the most — inbound messages.
+    this._messageGateway.on("message:inbound", (message) => {
+      void this._handleInboundMessage(message).catch((err) =>
+        this._logger.error(
+          { err },
+          "unhandled error in inbound message handler",
+        ),
+      );
+    });
     this._messageGateway.on("message:recalled", this._handleMessageRecall);
+    this._messageGateway.on("card:action", this._handleCardAction);
+  }
+
+  private _initSetupFlow(): void {
+    this._setupFlow = new SetupFlow({
+      workspaceStore: this._workspaceStore,
+      feishuChannels: this._feishuChannels,
+    });
+  }
+
+  private _initSwitchFlow(): void {
+    this._switchFlow = new SwitchFlow({
+      workspaceStore: this._workspaceStore,
+      feishuChannels: this._feishuChannels,
+    });
+  }
+
+  private _initGroupFlow(): void {
+    this._groupFlow = new GroupFlow({
+      feishuChannels: this._feishuChannels,
+      setupFlow: this._setupFlow,
+      db: this._database.db,
+    });
+  }
+
+  private _initSettingFlow(): void {
+    this._settingFlow = new SettingFlow({
+      workspaceStore: this._workspaceStore,
+      feishuChannels: this._feishuChannels,
+      db: this._database.db,
+    });
+  }
+
+  private _initReposFlow(): void {
+    this._reposFlow = new ReposFlow({
+      feishuChannels: this._feishuChannels,
+    });
+  }
+
+  private _initPermissionFlow(): void {
+    this._permissionFlow = new PermissionFlow({
+      feishuChannels: this._feishuChannels,
+    });
   }
 
   /**
@@ -112,18 +275,180 @@ class Kernel {
     await this._sessionManager.start();
     await this._taskDispatcher.start();
     await this._honoServer.start();
+    this._publishPermissionEndpointEnv();
     await this._messageGateway.start();
+    this._registerShutdownHandlers();
+  }
+
+  /**
+   * Graceful shutdown: expire every outstanding interactive card (permission,
+   * clarifying question, codex-resume) so a restart leaves no card that looks
+   * live but can never resolve — the agent subprocesses awaiting them are
+   * killed with this process. Runs while the Feishu channels are still
+   * connected so the in-place card updates land. Idempotent.
+   */
+  async stop(reason?: string): Promise<void> {
+    if (this._shuttingDown) return;
+    this._shuttingDown = true;
+    this._logger.info({ reason }, "kernel shutting down; expiring open cards");
+    try {
+      await this._permissionFlow.expireAllPending();
+      await this._expireCodexResumeCards();
+    } catch (err) {
+      this._logger.error({ err }, "error while expiring cards on shutdown");
+    }
+  }
+
+  /**
+   * Wire SIGINT/SIGTERM to {@link Kernel.stop} so an operator restart or a
+   * `bun --watch` reload expires open cards before the process exits.
+   */
+  private _registerShutdownHandlers(): void {
+    const onSignal = (signal: NodeJS.Signals) => {
+      void this.stop(signal).finally(() => process.exit(0));
+    };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+  }
+
+  /** Expire any open codex-resume cards left in the in-memory registry. */
+  private async _expireCodexResumeCards(): Promise<void> {
+    const entries = [...this._codexResumeRestarts.entries()];
+    this._codexResumeRestarts.clear();
+    for (const [messageId, pending] of entries) {
+      const channelId = pending.message.channel_id;
+      const channel = channelId
+        ? this._feishuChannels.get(channelId)
+        : undefined;
+      if (!channel) continue;
+      try {
+        await channel.updateRawCard(messageId, buildCodexResumeExpiredCard());
+      } catch (err) {
+        this._logger.warn(
+          { err, message_id: messageId },
+          "failed to expire codex resume card on shutdown",
+        );
+      }
+    }
+  }
+
+  /**
+   * Expose the internal approval endpoint + per-boot token via
+   * `process.env` so runners in `src/community/*` can pick them up
+   * without importing from `@/kernel` (which would reverse the
+   * dependency direction). The MCP subprocess spawned by Claude
+   * reads these at spawn time; the host only advertises them after
+   * Hono has bound its port.
+   */
+  private _publishPermissionEndpointEnv(): void {
+    const port = parseInt(Bun.env.AGENTARA_SERVICE_PORT ?? "1984", 10);
+    // Force localhost — the endpoint is not internet-reachable even
+    // if Hono binds to 0.0.0.0, because the bearer token rotates per
+    // boot and isn't persisted.
+    const url = `http://127.0.0.1:${port}/internal/permission/request`;
+    process.env.AGENTARA_PERMISSION_URL = url;
+    process.env.AGENTARA_PERMISSION_TOKEN = this._permissionFlow.apiToken;
   }
 
   private _handleInboundMessage = async (message: UserMessage) => {
-    const text = extractTextContent(message).trim();
+    // Feishu substitutes @mentions as `@_user_N` placeholders. Two-tier
+    // stripping:
+    //   - Always drop LEADING placeholder runs so users can `@bot /foo` in
+    //     any context (new session, inside a thread, etc.) and still hit
+    //     gateway-level slash routing.
+    //   - On the first message of a session, strip ALL placeholders — the
+    //     whole line is the user summoning the bot; nothing else in it
+    //     references a real collaborator.
+    // Non-leading placeholders are preserved mid-session so real @-mentions
+    // (e.g. `/allow @other_user`, or regular chatter) aren't mangled.
+    const isSessionStart = !this._sessionManager.existsSession(
+      message.session_id,
+    );
+    const rawText = extractTextContent(message);
+    const trimmed = rawText.trim().replace(/^(?:@_user_\d+\s*)+/, "");
+    const text = isSessionStart
+      ? trimmed.replace(/@_user_\d+/g, "").trim()
+      : trimmed.trim();
 
-    // Handle /stop command
+    // Handle /stop command (kernel-owned because it talks to TaskDispatcher)
     if (text === "/stop") {
       await this._handleStopCommand(message);
       return;
     }
 
+    // Handle /setup command (kernel-owned — renders an interactive card and
+    // awaits a card:action callback rather than returning a plain text reply).
+    if (text === "/setup") {
+      await this._setupFlow.start(message);
+      return;
+    }
+
+    // Handle /switch command (kernel-owned — interactive card). Available in
+    // both group chats and P2P since switching binding only touches metadata.
+    if (text === "/switch") {
+      await this._switchFlow.start(message);
+      return;
+    }
+
+    // Handle /setting + /workspaces commands (kernel-owned — interactive
+    // panel). Both open the same main card; the name duplication is just a
+    // convenience shortcut for users who only want the workspace view.
+    if (text === "/setting" || text === "/workspaces") {
+      await this._settingFlow.start(message);
+      return;
+    }
+
+    // Handle /repos command (kernel-owned — interactive card to manage
+    // REPOS.md entries the same way /setting manages workspaces).
+    if (text === "/repos") {
+      await this._reposFlow.start(message);
+      return;
+    }
+
+    // Handle /group command (kernel-owned — orchestrates create-chat +
+    // transfer-owner + auto /setup). Takes args, so match the prefix rather
+    // than equality.
+    if (text === "/group" || text.startsWith("/group ")) {
+      await this._groupFlow.start(message);
+      return;
+    }
+
+    // Handle /new command (kernel-owned — forks a fresh session + fresh
+    // Feishu thread, optionally carrying the post-slash text as the first
+    // agent prompt). Equivalent to @-mentioning the bot in the main chat.
+    if (isNewCommand(text)) {
+      await this._handleNewCommand(message, text);
+      return;
+    }
+
+    // Gateway-level slash commands: any `/`-prefixed message is resolved
+    // here first.
+    //   1. Registered command → run it and stop.
+    //   2. Passthrough-whitelisted (e.g. `/compact`) → fall through to the
+    //      normal agent dispatch so the underlying CLI (Claude Code) handles
+    //      its own slash command.
+    //   3. Anything else → reply "unknown command" rather than wasting an
+    //      agent turn on a likely typo.
+    if (text.startsWith("/")) {
+      const handled = await this._tryHandleCommand(message, text);
+      if (handled) return;
+      const parsed = parseCommand(text);
+      if (!parsed || !isPassthroughCommand(parsed.name)) {
+        await this._replyUnknownCommand(message, text);
+        return;
+      }
+      // Whitelisted passthrough — fall through to the agent dispatch below.
+    }
+
+    // On the first message of a new session, kick off a best-effort
+    // fetch + ff-pull across the workspace so the agent sees latest remote
+    // state. Fire-and-forget: the pull is atomic at the git level, the
+    // agent dispatch queue gives it a head start, and we don't want a
+    // flaky network to block the user's first turn.
+    if (isSessionStart && message.chat_id) {
+      this._autoSyncOnSessionStart(message.chat_id);
+    }
+
     const task: InboundMessageTaskPayload = {
       type: "inbound_message",
       message,
@@ -131,6 +456,231 @@ class Kernel {
     await this._taskDispatcher.dispatch(message.session_id, task);
   };
 
+  private _autoSyncOnSessionStart(chatId: string): void {
+    const resolution = this._workspaceStore.resolve(chatId);
+    if (!resolution.binding) return;
+    const workspacePath = resolution.binding.workspace_path;
+    syncWorkspace(workspacePath, { pull: true, timeout_ms: 15_000 })
+      .then((results) => {
+        const ff = results.filter((r) => r.status === "fast_forwarded");
+        if (ff.length > 0) {
+          this._logger.info(
+            {
+              chat_id: chatId,
+              workspace: workspacePath,
+              fast_forwarded: ff.map((r) => ({
+                repo: r.name,
+                branch: r.branch,
+                before: r.before_sha,
+                after: r.after_sha,
+              })),
+            },
+            "session-start auto-sync fast-forwarded",
+          );
+        }
+      })
+      .catch((err) => {
+        this._logger.warn(
+          { err, chat_id: chatId, workspace: workspacePath },
+          "session-start auto-sync failed",
+        );
+      });
+  }
+
+  private _handleNewCommand = async (message: UserMessage, text: string) => {
+    // Feishu threads don't nest: replying to an already-threaded message
+    // with reply_in_thread:true stays in the same thread. Running /new
+    // inside a thread would silently fold the "new" session into the
+    // existing one and overwrite its thread→session mapping. Reject.
+    if (message.thread_id) {
+      const reply = buildNewCommandRejectionReply();
+      await this._replyTextOrCard(message, reply.text, reply.card, "new");
+      return;
+    }
+
+    const prompt = extractNewPrompt(text);
+    if (!prompt) {
+      const reply = buildNewCommandUsageReply();
+      await this._replyTextOrCard(message, reply.text, reply.card, "new");
+      return;
+    }
+
+    // Fork: fresh session_id so isSessionStart flips true, and
+    // thread_id=undefined so replyMessage(replyInThread:true) creates a
+    // brand-new Feishu thread rooted at this user message.
+    const newMessage = createFreshUserMessage(message, prompt, uuid());
+    this._logger.info(
+      {
+        old_session_id: message.session_id,
+        new_session_id: newMessage.session_id,
+        chat_id: message.chat_id,
+        message_id: message.id,
+      },
+      "/new starting fresh session + thread",
+    );
+    if (newMessage.chat_id) {
+      this._autoSyncOnSessionStart(newMessage.chat_id);
+    }
+    await this._taskDispatcher.dispatch(newMessage.session_id, {
+      type: "inbound_message",
+      message: newMessage,
+    });
+  };
+
+  private _replyUnknownCommand = async (
+    message: UserMessage,
+    text: string,
+  ): Promise<void> => {
+    const reply = buildUnknownCommandReply(text);
+    await this._replyTextOrCard(message, reply.text, reply.card, "unknown");
+  };
+
+  private _tryHandleCommand = async (
+    message: UserMessage,
+    text: string,
+  ): Promise<boolean> => {
+    const parsed = parseCommand(text);
+    if (!parsed) return false;
+    const handler = this._commandRegistry.get(parsed.name);
+    if (!handler) return false;
+    let replyText: string;
+    let replyCard: CardCommandResult | null = null;
+    try {
+      const result = await handler.execute({
+        message,
+        args: parsed.args,
+        raw: parsed.raw,
+        workspaceStore: this._workspaceStore,
+        feishuChannels: this._feishuChannels,
+        sessionManager: this._sessionManager,
+        logger: this._logger,
+      });
+      if (typeof result === "string") {
+        replyText = result;
+      } else if (result.kind === "deferred_card") {
+        await this._handleDeferredCard(message, result, parsed.name);
+        return true;
+      } else {
+        replyText = result.fallback_text;
+        replyCard = result;
+      }
+    } catch (err) {
+      this._logger.error(
+        { err, command: parsed.name, chat_id: message.chat_id },
+        "command handler failed",
+      );
+      replyText = `❌ 命令 \`/${parsed.name}\` 执行失败：${(err as Error).message}`;
+    }
+    await this._replyTextOrCard(
+      message,
+      replyText,
+      replyCard?.card,
+      parsed.name,
+    );
+    return true;
+  };
+
+  /**
+   * Drive a {@link DeferredCardCommandResult}: post the pending card, run the
+   * slow work in the background, then patch the same message with the final
+   * card. Every step is guarded — a failure to render, run, or patch is
+   * logged but never allowed to escape (which would crash the process via an
+   * unhandled rejection on the fire-and-forget inbound handler).
+   */
+  private async _handleDeferredCard(
+    message: UserMessage,
+    result: DeferredCardCommandResult,
+    commandName: string,
+  ): Promise<void> {
+    const channel = message.channel_id
+      ? this._feishuChannels.get(message.channel_id)
+      : undefined;
+
+    // No card-capable channel: just run and reply with the final card/text.
+    if (!channel || !message.chat_id) {
+      try {
+        const finalCard = await result.run();
+        await this._replyTextOrCard(
+          message,
+          result.fallback_text,
+          finalCard,
+          commandName,
+        );
+      } catch (err) {
+        this._logger.error(
+          { err, command: commandName },
+          "deferred command failed",
+        );
+        await this._replyTextOrCard(
+          message,
+          `❌ 命令 \`/${commandName}\` 执行失败：${(err as Error).message}`,
+          undefined,
+          commandName,
+        );
+      }
+      return;
+    }
+
+    let cardMessageId: string;
+    try {
+      cardMessageId = await channel.sendRawCard(message.chat_id, result.initial, {
+        replyTo: message.id,
+        replyInThread: false,
+      });
+    } catch (err) {
+      // Couldn't show the pending card; still run the work and reply with the
+      // final result through the text-safe path so the user isn't left hanging.
+      this._logger.error(
+        { err, command: commandName, message_id: message.id },
+        "deferred initial card failed; falling back to text",
+      );
+      void result
+        .run()
+        .then((finalCard) =>
+          this._replyTextOrCard(
+            message,
+            result.fallback_text,
+            finalCard,
+            commandName,
+          ),
+        )
+        .catch((runErr) =>
+          this._logger.error(
+            { err: runErr, command: commandName },
+            "deferred run failed after initial card error",
+          ),
+        );
+      return;
+    }
+
+    // Fire-and-forget the slow work; fully guarded so it can never crash.
+    void (async () => {
+      try {
+        const finalCard = await result.run();
+        await channel.updateRawCard(cardMessageId, finalCard);
+      } catch (err) {
+        this._logger.error(
+          { err, command: commandName, card_message_id: cardMessageId },
+          "deferred command run failed",
+        );
+        try {
+          await channel.updateRawCard(
+            cardMessageId,
+            buildCommandCard({
+              title: "执行失败",
+              lines: [`❌ ${(err as Error).message}`],
+            }),
+          );
+        } catch (patchErr) {
+          this._logger.error(
+            { err: patchErr, card_message_id: cardMessageId },
+            "deferred failure card update failed",
+          );
+        }
+      }
+    })();
+  }
+
   private _handleStopCommand = async (message: UserMessage) => {
     const sessionId = message.session_id;
     const runningTaskId =
@@ -138,20 +688,94 @@ class Kernel {
 
     if (runningTaskId) {
       await this._taskDispatcher.deleteTask(runningTaskId);
-      await this._messageGateway.replyMessage(message.id, {
-        role: "assistant",
-        session_id: sessionId,
-        content: [{ type: "text", text: "Task stopped." }],
-      });
+      await this._replyTextOrCard(
+        message,
+        "✅ 任务已取消。",
+        buildCommandCard({
+          title: "停止任务",
+          lines: ["✅ 任务已取消。"],
+        }),
+        "stop",
+      );
     } else {
-      await this._messageGateway.replyMessage(message.id, {
-        role: "assistant",
-        session_id: sessionId,
-        content: [{ type: "text", text: "No running task found." }],
-      });
+      await this._replyTextOrCard(
+        message,
+        "ℹ️  当前 session 没有正在执行的任务。",
+        buildCommandCard({
+          title: "停止任务",
+          lines: ["ℹ️  当前 session 没有正在执行的任务。"],
+        }),
+        "stop",
+      );
     }
   };
 
+  private async _replyTextOrCard(
+    message: UserMessage,
+    text: string,
+    card?: Card,
+    commandName?: string,
+  ): Promise<void> {
+    const channel = message.channel_id
+      ? this._feishuChannels.get(message.channel_id)
+      : undefined;
+
+    if (card && message.chat_id && channel) {
+      try {
+        await channel.sendRawCard(message.chat_id, card, {
+          replyTo: message.id,
+          replyInThread: false,
+        });
+        return;
+      } catch (err) {
+        this._logger.error(
+          {
+            err,
+            command: commandName,
+            message_id: message.id,
+            chat_id: message.chat_id,
+          },
+          "command card reply failed; falling back to text",
+        );
+      }
+    }
+
+    // Text fallback. This must never throw out of here: an unhandled
+    // rejection on the fire-and-forget inbound handler crashes the process.
+    try {
+      await this._messageGateway.replyMessage(
+        message.id,
+        {
+          role: "assistant",
+          session_id: message.session_id,
+          content: [{ type: "text", text }],
+        },
+        {
+          channelId: message.channel_id,
+          streaming: false,
+          replyInThread: false,
+        },
+      );
+    } catch (err) {
+      this._logger.error(
+        { err, command: commandName, message_id: message.id },
+        "text fallback reply failed; trying plain text",
+      );
+      // Last resort: a real plain-text message (not a card reply, which is
+      // what just failed) posted straight to the chat.
+      if (channel && message.chat_id) {
+        try {
+          await channel.sendPlainText(message.chat_id, text);
+        } catch (plainErr) {
+          this._logger.error(
+            { err: plainErr, message_id: message.id },
+            "plain-text fallback also failed; giving up",
+          );
+        }
+      }
+    }
+  }
+
   private _handleMessageRecall = async (
     messageId: string,
     channelId: string,
@@ -166,6 +790,50 @@ class Kernel {
     }
   };
 
+  /**
+   * Route card-action callbacks by the `action_name` discriminator. Each
+   * interactive flow owns its own `action_name`; unknown actions are logged
+   * and dropped.
+   */
+  private _handleCardAction = async (payload: CardActionPayload) => {
+    if (payload.action_name === "setup_submit") {
+      await this._setupFlow.handleSubmit(payload);
+      return;
+    }
+    if (payload.action_name === SETUP_DISMISS_ACTION) {
+      await this._setupFlow.handleDismiss(payload);
+      return;
+    }
+    if (payload.action_name === "switch_submit") {
+      await this._switchFlow.handleSubmit(payload);
+      return;
+    }
+    if (payload.action_name === PERMISSION_ACTION) {
+      await this._permissionFlow.handleDecide(payload);
+      return;
+    }
+    if (payload.action_name === QUESTION_ACTION) {
+      await this._permissionFlow.handleQuestionSubmit(payload);
+      return;
+    }
+    if (payload.action_name === CODEX_RESUME_RESTART_ACTION) {
+      await this._handleCodexResumeRestart(payload);
+      return;
+    }
+    if (payload.action_name.startsWith("setting_")) {
+      await this._settingFlow.handleAction(payload);
+      return;
+    }
+    if (payload.action_name.startsWith("repos_")) {
+      await this._reposFlow.handleAction(payload);
+      return;
+    }
+    this._logger.warn(
+      { action_name: payload.action_name, message_id: payload.message_id },
+      "unhandled card action",
+    );
+  };
+
   private _handleInboundMessageTask = async (
     taskId: string,
     sessionId: string,
@@ -173,8 +841,14 @@ class Kernel {
     signal?: AbortSignal,
   ) => {
     const inboundMessage = payload.message;
+    const resolution = this._workspaceStore.resolve(inboundMessage.chat_id);
     const session = await this._sessionManager.resolveSession(sessionId, {
       channelId: inboundMessage.channel_id,
+      chatId: inboundMessage.chat_id,
+      threadId: inboundMessage.thread_id,
+      cwd: resolution.cwd,
+      envExtras: resolution.envExtras,
+      forceNewRunnerSession: payload.forceNewRunnerSession,
       firstMessage: inboundMessage,
     });
     let contents: AssistantMessage["content"] = [
@@ -195,31 +869,199 @@ class Kernel {
       },
     );
     contents = [];
-    const stream = await session.stream(inboundMessage, { signal });
     let lastMessage: AssistantMessage | undefined;
-    for await (const message of stream) {
-      if (message.role === "assistant") {
-        contents.push(...message.content);
+    // Footer stats come from the most recent turn that actually reported
+    // usage — trailing synthetic messages (compaction notices) carry no
+    // usage/model and would otherwise blank out the footer.
+    let lastUsageMessage: AssistantMessage | undefined;
+    try {
+      const stream = await session.stream(inboundMessage, { signal });
+      for await (const message of stream) {
+        if (message.role === "assistant") {
+          contents.push(...message.content);
+          await this._messageGateway.updateMessageContent(
+            { ...outboundMessage, content: contents },
+            {
+              streaming: true,
+            },
+          );
+          lastMessage = message;
+          if (message.usage) lastUsageMessage = message;
+        }
+      }
+      if (!lastMessage) {
+        throw new Error("No assistant message received from the agent.");
+      }
+    } catch (err) {
+      if (err instanceof CodexMissingResumeError) {
+        await this._handleCodexMissingResume(
+          err,
+          inboundMessage,
+          session.id,
+          outboundMessage,
+        );
+        throw err;
+      }
+      const failureContent = signal?.aborted
+        ? buildAgentCancelledContent()
+        : buildAgentFailureContent(err);
+      try {
         await this._messageGateway.updateMessageContent(
-          { ...outboundMessage, content: contents },
+          { ...outboundMessage, content: failureContent },
           {
-            streaming: true,
+            streaming: false,
           },
         );
-        lastMessage = message;
+      } catch (updateErr) {
+        this._logger.error(
+          {
+            err: updateErr,
+            session_id: session.id,
+            outbound_message_id: outboundMessage.id,
+          },
+          "failed to update assistant message after agent failure",
+        );
       }
-    }
-    if (!lastMessage) {
-      throw new Error("No assistant message received from the agent.");
+      throw err;
     }
     await this._messageGateway.updateMessageContent(
       { ...outboundMessage, content: contents },
       {
         streaming: false,
+        footer: await this._buildCardFooter(lastUsageMessage),
       },
     );
   };
 
+  /**
+   * Assemble the finalized card's footer stats: context-window occupancy
+   * for the latest turn (from the agent's reported token usage) plus the
+   * account's rolling 5-hour / 7-day quota. Scoped to runs that surface
+   * token usage (Claude) — other runners get no footer. Best-effort: a
+   * failed quota lookup still returns the context bar, and any error
+   * yields `undefined` so a footer never breaks a reply.
+   */
+  private async _buildCardFooter(
+    lastMessage?: AssistantMessage,
+  ): Promise<CardFooterStats | undefined> {
+    const usage = lastMessage?.usage;
+    if (!usage) return undefined;
+    try {
+      const stats: CardFooterStats = {};
+      // Prefer the model the runner actually resolved; fall back to the
+      // configured one (often unset). Used for both display and the
+      // context-window limit.
+      const model = lastMessage?.model ?? config.agents.default.model;
+      if (model) stats.model = model;
+      const usedTokens =
+        (usage.input_tokens ?? 0) +
+        (usage.cache_read_input_tokens ?? 0) +
+        (usage.cache_creation_input_tokens ?? 0) +
+        (usage.output_tokens ?? 0);
+      if (usedTokens > 0) {
+        stats.context = {
+          used_tokens: usedTokens,
+          limit_tokens: contextLimitForModel(model),
+        };
+      }
+      const quota = await getClaudeUsageCached();
+      if (quota) {
+        stats.five_hour = {
+          utilization: quota.five_hour.utilization,
+          resets_at: quota.five_hour.resets_at,
+        };
+        stats.seven_day = {
+          utilization: quota.seven_day.utilization,
+          resets_at: quota.seven_day.resets_at,
+        };
+      }
+      return Object.keys(stats).length > 0 ? stats : undefined;
+    } catch (err) {
+      this._logger.warn({ err }, "failed to build card footer stats");
+      return undefined;
+    }
+  }
+
+  private async _handleCodexMissingResume(
+    err: CodexMissingResumeError,
+    inboundMessage: UserMessage,
+    sessionId: string,
+    outboundMessage: AssistantMessage,
+  ): Promise<void> {
+    const card = buildCodexResumeMissingCard({ resumeId: err.resumeId });
+    const channel =
+      inboundMessage.channel_id && inboundMessage.chat_id
+        ? this._feishuChannels.get(inboundMessage.channel_id)
+        : undefined;
+    if (channel) {
+      try {
+        await channel.updateRawCard(outboundMessage.id, card);
+        this._codexResumeRestarts.set(outboundMessage.id, {
+          sessionId,
+          message: inboundMessage,
+        });
+        return;
+      } catch (updateErr) {
+        this._logger.error(
+          {
+            err: updateErr,
+            session_id: sessionId,
+            outbound_message_id: outboundMessage.id,
+          },
+          "failed to update Codex resume recovery card",
+        );
+      }
+    }
+
+    await this._messageGateway.updateMessageContent(
+      {
+        ...outboundMessage,
+        content: [
+          {
+            type: "text",
+            text: formatCodexResumeMissingText(err.resumeId),
+          },
+        ],
+      },
+      { streaming: false },
+    );
+  }
+
+  private async _handleCodexResumeRestart(
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const pending = this._codexResumeRestarts.get(payload.message_id);
+    const channel = this._feishuChannels.get(payload.channel_id);
+    if (!pending) {
+      if (channel) {
+        await channel.updateRawCard(
+          payload.message_id,
+          buildCodexResumeExpiredCard(),
+        );
+      }
+      return;
+    }
+    this._codexResumeRestarts.delete(payload.message_id);
+    if (channel) {
+      await channel.updateRawCard(
+        payload.message_id,
+        buildCodexResumeRestartingCard(),
+      );
+    }
+    this._sessionManager.resetRunnerSessionId(pending.sessionId);
+    await this._taskDispatcher.dispatch(pending.sessionId, {
+      type: "inbound_message",
+      message: pending.message,
+      forceNewRunnerSession: true,
+    });
+    if (channel) {
+      await channel.updateRawCard(
+        payload.message_id,
+        buildCodexResumeRestartedCard(),
+      );
+    }
+  }
+
   private _handleScheduledTask = async (
     _taskId: string,
     sessionId: string,
diff --git a/src/kernel/messaging/multi-channel-message-gateway.ts b/src/kernel/messaging/multi-channel-message-gateway.ts
index 1f82c70..17f0bf9 100644
--- a/src/kernel/messaging/multi-channel-message-gateway.ts
+++ b/src/kernel/messaging/multi-channel-message-gateway.ts
@@ -4,6 +4,8 @@ import EventEmitter from "eventemitter3";
 import type { DrizzleDB } from "@/data";
 import type {
   AssistantMessage,
+  CardActionPayload,
+  CardFooterStats,
   MessageChannel,
   MessageGateway,
   MessageGatewayEventTypes,
@@ -47,6 +49,9 @@ export class MultiChannelMessageGateway
     channel.on("message:recalled", (messageId: string, channelId: string) => {
       this.emit("message:recalled", messageId, channelId);
     });
+    channel.on("card:action", (payload: CardActionPayload) => {
+      this.emit("card:action", payload);
+    });
     this._logger.info(`Registered channel: ${channel.id}`);
   }
 
@@ -63,47 +68,57 @@ export class MultiChannelMessageGateway
 
   /**
    * Post a new assistant message without replying to an existing message.
-   * Routes to the correct channel based on session `channel_id`.
+   * Routes by the explicit `options.channelId` when provided, otherwise by the
+   * session's persisted `channel_id`.
    * @param message - The assistant message to post (without id).
+   * @param options - Optional settings.
    * @returns The posted message with id assigned.
    */
   async postMessage(
     message: Omit<AssistantMessage, "id">,
+    options?: { channelId?: string },
   ): Promise<AssistantMessage> {
-    const channel = this._resolveChannelForSession(message.session_id);
+    const channel = this._resolveChannelFor(message.session_id, options?.channelId);
     const result = await channel.postMessage(message);
     return result;
   }
 
   /**
    * Reply to an existing message.
-   * Routes to the correct channel based on session `channel_id`.
+   * Routes by the explicit `options.channelId` when provided, otherwise by the
+   * session's persisted `channel_id`. Pass `channelId` for gateway-level replies
+   * that fire before any Session is created.
    * @param messageId - ID of the message to reply to.
    * @param message - The assistant message to send (without id).
-   * @param options - Optional settings (e.g. streaming mode).
+   * @param options - Optional settings.
    * @returns The sent message with id assigned.
    */
   async replyMessage(
     messageId: string,
     message: Omit<AssistantMessage, "id">,
-    options?: { streaming?: boolean },
+    options?: {
+      streaming?: boolean;
+      channelId?: string;
+      replyInThread?: boolean;
+    },
   ): Promise<AssistantMessage> {
-    const channel = this._resolveChannelForSession(message.session_id);
+    const channel = this._resolveChannelFor(message.session_id, options?.channelId);
     const result = await channel.replyMessage(messageId, message, options);
     return result;
   }
 
   /**
    * Update the content of an existing message.
-   * Routes to the correct channel based on session `channel_id`.
+   * Routes by the explicit `options.channelId` when provided, otherwise by the
+   * session's persisted `channel_id`.
    * @param message - The assistant message with updated content.
-   * @param options - Optional settings (e.g. streaming mode).
+   * @param options - Optional settings.
    */
   async updateMessageContent(
     message: AssistantMessage,
-    options?: { streaming?: boolean },
+    options?: { streaming?: boolean; channelId?: string; footer?: CardFooterStats },
   ): Promise<void> {
-    const channel = this._resolveChannelForSession(message.session_id);
+    const channel = this._resolveChannelFor(message.session_id, options?.channelId);
     await channel.updateMessageContent(message, options);
   }
 
@@ -120,13 +135,18 @@ export class MultiChannelMessageGateway
   }
 
   /**
-   * Resolves the correct channel for a session by querying the `channel_id`
-   * from the sessions table.
-   * @param sessionId - The session identifier.
-   * @returns The matching MessageChannel.
-   * @throws If the session has no channel_id or the channel is not registered.
+   * Resolves the target channel. If `explicitChannelId` is provided, it wins
+   * (used for gateway-level replies before any Session is persisted). Otherwise
+   * falls back to querying `channel_id` from the sessions table.
+   * @throws If neither path yields a registered channel.
    */
-  private _resolveChannelForSession(sessionId: string): MessageChannel {
+  private _resolveChannelFor(
+    sessionId: string,
+    explicitChannelId?: string,
+  ): MessageChannel {
+    if (explicitChannelId) {
+      return this._resolveChannel(explicitChannelId);
+    }
     const row = this._db
       .select({ channel_id: sessions.channel_id })
       .from(sessions)
diff --git a/src/kernel/permission/index.ts b/src/kernel/permission/index.ts
new file mode 100644
index 0000000..4059d10
--- /dev/null
+++ b/src/kernel/permission/index.ts
@@ -0,0 +1,14 @@
+export {
+  buildPermissionCard,
+  buildPermissionResultCard,
+  buildQuestionCard,
+  buildQuestionResultCard,
+  PERMISSION_ACTION,
+  QUESTION_ACTION,
+  type PermissionCallbackValue,
+} from "./permission-card";
+export {
+  PermissionFlow,
+  type PermissionDecision,
+  type PermissionRequestParams,
+} from "./permission-flow";
diff --git a/src/kernel/permission/permission-card.ts b/src/kernel/permission/permission-card.ts
new file mode 100644
index 0000000..e48e3f2
--- /dev/null
+++ b/src/kernel/permission/permission-card.ts
@@ -0,0 +1,406 @@
+import { z } from "zod";
+
+import type {
+  ButtonElement,
+  Card,
+  CheckerElement,
+  ColumnSetElement,
+  Element,
+  FormElement,
+  SelectStaticElement,
+} from "../../community/feishu/messaging/types";
+import {
+  buildCardIntro,
+  buildMarkdown,
+  buildResultCard,
+} from "../setup/card-ui";
+
+/**
+ * `action` discriminator echoed back on `card.action.trigger` when the
+ * user clicks Approve or Deny. Matched by {@link PermissionFlow}.
+ */
+export const PERMISSION_ACTION = "permission_decide";
+
+/**
+ * Payload attached to each permission button's callback. The decision is
+ * the click result; `request_id` correlates with the pending map in
+ * {@link PermissionFlow}.
+ *
+ * `allow_session` is a session-scoped "always allow this tool" shortcut —
+ * the flow adds the tool name to an in-memory allow list keyed by
+ * `session_id`, so subsequent calls for the same tool don't prompt again.
+ * Scope is the current session only and the list clears on kernel restart.
+ *
+ * The index signature is there only to satisfy the `CallbackValue =
+ * Record<string, unknown>` contract on {@link CallbackBehavior}; the
+ * real shape is the three named fields above it.
+ */
+export interface PermissionCallbackValue {
+  action: typeof PERMISSION_ACTION;
+  request_id: string;
+  decision: "allow" | "deny" | "allow_session";
+  [key: string]: unknown;
+}
+
+/**
+ * Build the permission-request card shown to the initiator. The body
+ * stays intentionally flat: a short summary line + a collapsible JSON
+ * block for the raw input, so scanability wins for simple tools while
+ * power users can still inspect the exact args.
+ */
+export function buildPermissionCard(options: {
+  request_id: string;
+  tool_name: string;
+  tool_input: unknown;
+  initiator_open_id: string;
+}): Card {
+  const preview = _formatInputPreview(options.tool_input);
+  const elements: Element[] = [
+    buildCardIntro({
+      title: "🔒 权限请求",
+      subtitle: `Claude Code 请求调用工具 \`${options.tool_name}\``,
+    }),
+    buildMarkdown(
+      [
+        `- 发起人：<at id=${options.initiator_open_id}></at>`,
+        `- 工具：\`${options.tool_name}\``,
+      ].join("\n"),
+    ),
+  ];
+
+  if (preview) {
+    elements.push(
+      buildMarkdown("<font color='grey'>调用参数</font>", {
+        text_size: "notation",
+      }),
+      buildMarkdown("```json\n" + preview + "\n```"),
+    );
+  }
+
+  elements.push(...buildButtonRows(options.request_id));
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: {
+        content: `🔒 权限请求：${options.tool_name}`,
+      },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
+
+/**
+ * Terminal card shown after a decision is made (approve / deny / timeout
+ * / wrong operator / already-decided). Replaces the original card in
+ * place.
+ */
+export function buildPermissionResultCard(options: {
+  tool_name: string;
+  outcome:
+    | "allowed"
+    | "allowed_session"
+    | "denied"
+    | "timeout"
+    | "wrong_operator"
+    | "already_decided"
+    | "expired";
+  decided_by_open_id?: string;
+}): Card {
+  const { tool_name, outcome } = options;
+  const decided_by = options.decided_by_open_id;
+  let summary: string;
+  switch (outcome) {
+    case "allowed":
+      summary = decided_by
+        ? `✅ <at id=${decided_by}></at> 已批准 \`${tool_name}\`。`
+        : `✅ 已批准 \`${tool_name}\`。`;
+      break;
+    case "allowed_session":
+      summary = decided_by
+        ? `🔓 <at id=${decided_by}></at> 已批准 \`${tool_name}\`，并在本次会话内对该工具放行。`
+        : `🔓 已批准 \`${tool_name}\`，并在本次会话内对该工具放行。`;
+      break;
+    case "denied":
+      summary = decided_by
+        ? `🚫 <at id=${decided_by}></at> 已拒绝 \`${tool_name}\`。`
+        : `🚫 已拒绝 \`${tool_name}\`。`;
+      break;
+    case "timeout":
+      summary = `⚠️  5 分钟内未响应，已按拒绝处理 \`${tool_name}\`。`;
+      break;
+    case "wrong_operator":
+      summary = "🚫 这不是你的权限卡片，只有发起人可以决定。";
+      break;
+    case "already_decided":
+      summary = "ℹ️  该权限请求已经处理过。";
+      break;
+    case "expired":
+      summary = "⚠️  该权限请求已失效。";
+      break;
+  }
+  return buildResultCard({
+    title: "权限请求",
+    summary,
+  });
+}
+
+function _formatInputPreview(input: unknown): string {
+  if (input === undefined || input === null) return "";
+  try {
+    const text = JSON.stringify(input, null, 2);
+    if (text.length <= 1200) return text;
+    return text.slice(0, 1200) + "\n… (truncated)";
+  } catch {
+    return String(input);
+  }
+}
+
+function buildButtonRows(requestId: string): Element[] {
+  const mkValue = (
+    decision: PermissionCallbackValue["decision"],
+  ): PermissionCallbackValue => ({
+    action: PERMISSION_ACTION,
+    request_id: requestId,
+    decision,
+  });
+  const approveBtn: ButtonElement = {
+    tag: "button",
+    name: "permission_allow",
+    text: { tag: "plain_text", content: "✅ 批准" },
+    type: "primary",
+    width: "fill",
+    behaviors: [{ type: "callback", value: mkValue("allow") }],
+  };
+  const denyBtn: ButtonElement = {
+    tag: "button",
+    name: "permission_deny",
+    text: { tag: "plain_text", content: "🚫 拒绝" },
+    type: "danger",
+    width: "fill",
+    behaviors: [{ type: "callback", value: mkValue("deny") }],
+  };
+  const allowSessionBtn: ButtonElement = {
+    tag: "button",
+    name: "permission_allow_session",
+    text: {
+      tag: "plain_text",
+      content: "🔓 批准并在本次会话内不再询问该工具",
+    },
+    type: "default",
+    width: "fill",
+    behaviors: [{ type: "callback", value: mkValue("allow_session") }],
+  };
+  const primaryRow: ColumnSetElement = {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      { tag: "column", width: "weighted", weight: 1, elements: [approveBtn] },
+      { tag: "column", width: "weighted", weight: 1, elements: [denyBtn] },
+    ],
+  };
+  // The session-wide allow sits on its own row so its longer copy isn't
+  // squashed, and users don't mistake it for the single-shot approve.
+  return [primaryRow, allowSessionBtn];
+}
+
+// ---------------------------------------------------------------------------
+// AskUserQuestion — clarifying-question cards
+//
+// Claude Code's built-in `AskUserQuestion` tool rides the same
+// `--permission-prompt-tool` channel as ordinary tool approvals, but its
+// semantics differ: the user must *answer* multiple-choice questions, not
+// approve/deny a side effect. Returning `behavior:"allow"` without an
+// `answers` map makes Claude resolve the call with empty answers, so we
+// render a real form, collect selections, and echo them back as
+// `updatedInput: { questions, answers }`.
+// ---------------------------------------------------------------------------
+
+/**
+ * One choice inside an {@link AskUserQuestionItem}. Field names mirror the
+ * Claude tool contract verbatim (no underscore_case) so the payload round-trips
+ * unchanged.
+ */
+export const AskUserQuestionOption = z.object({
+  label: z.string(),
+  description: z.string().optional(),
+});
+export interface AskUserQuestionOption
+  extends z.infer<typeof AskUserQuestionOption> {}
+
+/**
+ * A single clarifying question. `multiSelect` allows picking more than one
+ * option; `header` is a short label Claude attaches for display.
+ */
+export const AskUserQuestionItem = z.object({
+  question: z.string(),
+  header: z.string().optional(),
+  options: z.array(AskUserQuestionOption).min(1),
+  multiSelect: z.boolean().optional(),
+});
+export interface AskUserQuestionItem
+  extends z.infer<typeof AskUserQuestionItem> {}
+
+/**
+ * The `tool_input` Claude sends when invoking `AskUserQuestion`. Parsed with
+ * {@link AskUserQuestionInput.safeParse} before rendering; a parse failure is
+ * treated as a deny so a malformed payload can't stall the tool call.
+ */
+export const AskUserQuestionInput = z.object({
+  questions: z.array(AskUserQuestionItem).min(1),
+});
+export interface AskUserQuestionInput
+  extends z.infer<typeof AskUserQuestionInput> {}
+
+/**
+ * `action` discriminator for the question form's submit button. Form-submit
+ * buttons carry no `behaviors[].value`, so this rides on the button `name`,
+ * which Feishu echoes as `action.name` and the channel maps to `action_name`.
+ */
+export const QUESTION_ACTION = "permission_question_submit";
+
+/** `form_value` field-name helpers for the question card. */
+export const QUESTION_FIELD = {
+  /** Single-select dropdown for question `qi`; value is the option index. */
+  select: (qi: number): string => `q${qi}`,
+  /** Multi-select checker for option `oi` of question `qi`. */
+  checker: (qi: number, oi: number): string => `q${qi}_o${oi}`,
+};
+
+/**
+ * Render an interactive form that surfaces Claude's clarifying questions.
+ * Single-select questions become a dropdown; multi-select questions become a
+ * column of checkers. `warning` is shown when a previous submit was rejected
+ * for being incomplete.
+ */
+export function buildQuestionCard(options: {
+  request_id: string;
+  questions: AskUserQuestionItem[];
+  initiator_open_id: string;
+  warning?: string;
+}): Card {
+  const formElements: Element[] = [];
+  options.questions.forEach((q, qi) => {
+    const heading = q.header?.trim() ? q.header.trim() : `问题 ${qi + 1}`;
+    formElements.push(buildMarkdown(`**${heading}**\n${q.question}`));
+    if (q.multiSelect) {
+      formElements.push(
+        buildMarkdown("<font color='grey'>可多选</font>", {
+          text_size: "notation",
+        }),
+      );
+      q.options.forEach((opt, oi) => {
+        const checker: CheckerElement = {
+          tag: "checker",
+          name: QUESTION_FIELD.checker(qi, oi),
+          text: { tag: "plain_text", content: _optionText(opt) },
+          checked: false,
+        };
+        formElements.push(checker);
+      });
+    } else {
+      const select: SelectStaticElement = {
+        tag: "select_static",
+        name: QUESTION_FIELD.select(qi),
+        placeholder: { tag: "plain_text", content: "请选择" },
+        options: q.options.map((opt, oi) => ({
+          text: { tag: "plain_text", content: _optionText(opt) },
+          value: String(oi),
+        })),
+        width: "fill",
+      };
+      formElements.push(select);
+    }
+  });
+  formElements.push(_buildQuestionSubmitButton());
+
+  const form: FormElement = {
+    tag: "form",
+    name: "permission_question_form",
+    elements: formElements,
+  };
+
+  const elements: Element[] = [
+    buildCardIntro({
+      title: "❓ 需要你的选择",
+      subtitle: "Claude Code 需要你回答以下问题才能继续",
+    }),
+    buildMarkdown(`- 发起人：<at id=${options.initiator_open_id}></at>`),
+  ];
+  if (options.warning) {
+    elements.push(
+      buildMarkdown(`<font color='red'>⚠️ ${options.warning}</font>`),
+    );
+  }
+  elements.push(form);
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: "❓ Claude 需要你回答" },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
+
+/**
+ * Terminal card shown after the question round-trip resolves (answered /
+ * timeout / already-answered / expired). Replaces the form in place.
+ */
+export function buildQuestionResultCard(options: {
+  outcome: "answered" | "timeout" | "already_answered" | "expired";
+  detail?: string[];
+}): Card {
+  let summary: string;
+  switch (options.outcome) {
+    case "answered":
+      summary = "✅ 已收到你的回答。";
+      break;
+    case "timeout":
+      summary = "⚠️  5 分钟内未回答，已按取消处理。";
+      break;
+    case "already_answered":
+      summary = "ℹ️  该问题已经回答过。";
+      break;
+    case "expired":
+      summary = "⚠️  该问题卡片已失效。";
+      break;
+  }
+  return buildResultCard({
+    title: "Claude 的问题",
+    summary,
+    detail: options.detail,
+  });
+}
+
+function _optionText(opt: AskUserQuestionOption): string {
+  const desc = opt.description?.trim();
+  const text = desc ? `${opt.label} — ${desc}` : opt.label;
+  return text.length > 100 ? text.slice(0, 99) + "…" : text;
+}
+
+function _buildQuestionSubmitButton(): ButtonElement {
+  return {
+    tag: "button",
+    name: QUESTION_ACTION,
+    text: { tag: "plain_text", content: "✅ 提交回答" },
+    type: "primary",
+    action_type: "form_submit",
+    width: "fill",
+  };
+}
diff --git a/src/kernel/permission/permission-flow.ts b/src/kernel/permission/permission-flow.ts
new file mode 100644
index 0000000..825f087
--- /dev/null
+++ b/src/kernel/permission/permission-flow.ts
@@ -0,0 +1,654 @@
+import { createLogger, uuid, type CardActionPayload, type Logger } from "@/shared";
+
+import type { FeishuMessageChannel } from "../../community/feishu/messaging/message-channel";
+
+import {
+  AskUserQuestionInput,
+  buildPermissionCard,
+  buildPermissionResultCard,
+  buildQuestionCard,
+  buildQuestionResultCard,
+  PERMISSION_ACTION,
+  QUESTION_FIELD,
+  type AskUserQuestionItem,
+  type PermissionCallbackValue,
+} from "./permission-card";
+
+/**
+ * Outcome returned by {@link PermissionFlow.request}. Shape mirrors
+ * Claude Code's `--permission-prompt-tool` contract so the MCP bridge
+ * can pass it through almost verbatim.
+ */
+export interface PermissionDecision {
+  behavior: "allow" | "deny";
+  /**
+   * Required by Claude on allow: the (possibly modified) tool input to
+   * actually run. We echo back the original input unchanged — we never
+   * mutate tool calls on the user's behalf.
+   */
+  updated_input?: Record<string, unknown>;
+  /** Optional deny reason shown to the model. */
+  message?: string;
+  decided_by: "user" | "timeout";
+}
+
+/**
+ * Parameters for a single permission-request round-trip. Everything
+ * here is routed into the card (for display) or the pending registry
+ * (for dispatch/validation).
+ */
+export interface PermissionRequestParams {
+  session_id: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  channel_id: string;
+  chat_id: string;
+  initiator_open_id: string;
+  /** Optional message id to anchor the card under (keeps reply chain intact). */
+  reply_to_message_id?: string;
+}
+
+/** Default auto-deny window when the initiator never clicks. */
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+interface PendingEntry {
+  request_id: string;
+  session_id: string;
+  tool_name: string;
+  initiator_open_id: string;
+  channel_id: string;
+  chat_id: string;
+  card_message_id: string;
+  created_at: number;
+  // eslint-disable-next-line no-unused-vars
+  resolve: (decision: PermissionDecision) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Pending state for one `AskUserQuestion` round-trip. Keyed by the card's
+ * `message_id` like {@link PendingEntry}, but carries the parsed questions so
+ * the submit handler can map `form_value` back to option labels.
+ */
+interface PendingQuestionEntry {
+  request_id: string;
+  session_id: string;
+  initiator_open_id: string;
+  channel_id: string;
+  chat_id: string;
+  card_message_id: string;
+  questions: AskUserQuestionItem[];
+  created_at: number;
+  // eslint-disable-next-line no-unused-vars
+  resolve: (decision: PermissionDecision) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Orchestrates one interactive permission round-trip per
+ * Claude-Code tool call:
+ *
+ * 1. `request(params)` renders an approve/deny card into the chat,
+ *    stores a pending entry keyed by the outbound card's `message_id`,
+ *    and returns a Promise that resolves when the user clicks or the
+ *    timeout fires.
+ * 2. The kernel routes `card:action` events with
+ *    `value.action === "permission_decide"` to `handleDecide(payload)`,
+ *    which validates the operator, resolves the pending promise, and
+ *    replaces the card with a terminal result card.
+ *
+ * Single-writer per request: we delete the pending entry before
+ * resolving, so duplicate clicks (or a timeout that races with a late
+ * click) don't double-resolve the promise.
+ */
+export class PermissionFlow {
+  private readonly _logger: Logger = createLogger("permission-flow");
+  private readonly _feishuChannels: Map<string, FeishuMessageChannel>;
+  private readonly _pending = new Map<string, PendingEntry>();
+  private readonly _pendingQuestions = new Map<string, PendingQuestionEntry>();
+  private readonly _timeoutMs: number;
+  /**
+   * Per-session allow list populated when the user picks "allow this tool
+   * for the whole session" on a permission card. Keyed by `session_id`;
+   * each value is the set of tool names approved for that session. In-memory
+   * only — a kernel restart drops the list so trust never survives across
+   * boots.
+   */
+  private readonly _sessionAllowlist = new Map<string, Set<string>>();
+
+  /**
+   * Process-lifetime shared secret used by the MCP stdio subprocess to
+   * call back into the kernel's internal permission endpoint. Rotated
+   * on every kernel boot; not persisted. Only reachable from localhost.
+   */
+  private readonly _apiToken: string = uuid();
+
+  constructor(deps: {
+    feishuChannels: Map<string, FeishuMessageChannel>;
+    timeoutMs?: number;
+  }) {
+    this._feishuChannels = deps.feishuChannels;
+    this._timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  /**
+   * Token the MCP subprocess must send in `Authorization: Bearer …` when
+   * calling the kernel's internal permission endpoint. Threaded into
+   * subprocess env at spawn time; never logged.
+   */
+  get apiToken(): string {
+    return this._apiToken;
+  }
+
+  /** Constant-time token comparison so unauthorized callers can't time us. */
+  verifyToken(candidate: string | undefined | null): boolean {
+    if (!candidate) return false;
+    if (candidate.length !== this._apiToken.length) return false;
+    let diff = 0;
+    for (let i = 0; i < candidate.length; i++) {
+      diff |= candidate.charCodeAt(i) ^ this._apiToken.charCodeAt(i);
+    }
+    return diff === 0;
+  }
+
+  /**
+   * Send a permission card to the initiator's chat and await a decision.
+   *
+   * Rejects only when we fail to send the card at all (no channel, API
+   * error) — the caller should treat that as a deny so the tool call
+   * doesn't silently stall.
+   */
+  async request(params: PermissionRequestParams): Promise<PermissionDecision> {
+    // AskUserQuestion needs answers, not approve/deny — route it to the
+    // dedicated question form before the approval machinery below.
+    if (params.tool_name === "AskUserQuestion") {
+      return this._requestQuestion(params);
+    }
+    const channel = this._feishuChannels.get(params.channel_id);
+    if (!channel) {
+      throw new Error(
+        `Permission request for unknown channel_id=${params.channel_id}`,
+      );
+    }
+    // Session-wide allow short-circuit: if the user has already opted to
+    // trust this tool for the whole session, skip the card and auto-approve.
+    if (this._isSessionAllowed(params.session_id, params.tool_name)) {
+      this._logger.info(
+        { session_id: params.session_id, tool_name: params.tool_name },
+        "permission auto-allowed from session allowlist",
+      );
+      return {
+        behavior: "allow",
+        updated_input: params.tool_input,
+        decided_by: "user",
+      };
+    }
+    const requestId = uuid();
+    const card = buildPermissionCard({
+      request_id: requestId,
+      tool_name: params.tool_name,
+      tool_input: params.tool_input,
+      initiator_open_id: params.initiator_open_id,
+    });
+
+    const cardMessageId = await channel.sendRawCard(params.chat_id, card, {
+      replyTo: params.reply_to_message_id,
+      // Keep the card inline with the original turn; threading would hide
+      // it from anyone not already following the topic.
+      replyInThread: false,
+    });
+
+    return new Promise<PermissionDecision>((resolve) => {
+      const timeout = setTimeout(() => {
+        const entry = this._pending.get(cardMessageId);
+        if (!entry) return;
+        this._pending.delete(cardMessageId);
+        this._logger.warn(
+          {
+            request_id: requestId,
+            session_id: params.session_id,
+            tool_name: params.tool_name,
+          },
+          "permission request timed out, auto-denying",
+        );
+        void this._tryUpdateCard(
+          params.channel_id,
+          cardMessageId,
+          buildPermissionResultCard({
+            tool_name: params.tool_name,
+            outcome: "timeout",
+          }),
+          "timeout",
+        );
+        resolve({
+          behavior: "deny",
+          message: "Permission request timed out after 5 minutes.",
+          decided_by: "timeout",
+        });
+      }, this._timeoutMs);
+
+      this._pending.set(cardMessageId, {
+        request_id: requestId,
+        session_id: params.session_id,
+        tool_name: params.tool_name,
+        initiator_open_id: params.initiator_open_id,
+        channel_id: params.channel_id,
+        chat_id: params.chat_id,
+        card_message_id: cardMessageId,
+        created_at: Date.now(),
+        resolve,
+        timeout,
+      });
+      this._logger.info(
+        {
+          request_id: requestId,
+          session_id: params.session_id,
+          tool_name: params.tool_name,
+          card_message_id: cardMessageId,
+        },
+        "permission card sent",
+      );
+    });
+  }
+
+  /**
+   * Entry point invoked from the kernel's `card:action` listener when the
+   * payload's `value.action === PERMISSION_ACTION`. Looks up the pending
+   * entry, validates the operator, and either resolves the Promise with
+   * the clicked decision or surfaces an error card.
+   */
+  async handleDecide(payload: CardActionPayload): Promise<void> {
+    const channel = this._feishuChannels.get(payload.channel_id);
+    if (!channel) {
+      this._logger.warn(
+        { channel_id: payload.channel_id },
+        "permission action for unknown channel",
+      );
+      return;
+    }
+    const entry = this._pending.get(payload.message_id);
+    if (!entry) {
+      await this._tryUpdateCard(
+        payload.channel_id,
+        payload.message_id,
+        buildPermissionResultCard({
+          tool_name: "(unknown)",
+          outcome: "already_decided",
+        }),
+        "already-decided",
+      );
+      return;
+    }
+    if (entry.initiator_open_id !== payload.operator_open_id) {
+      // Don't consume the pending entry — the initiator can still click.
+      // We don't mutate the card either: rewriting buttons on the fly
+      // races with the pending promise and risks losing them on failure.
+      // The clicker sees Feishu's generic ack toast; the card stays
+      // intact for the initiator to act on.
+      this._logger.info(
+        {
+          request_id: entry.request_id,
+          operator: payload.operator_open_id,
+          initiator: entry.initiator_open_id,
+        },
+        "non-initiator click on permission card; ignoring",
+      );
+      return;
+    }
+
+    const value = payload.value as unknown as PermissionCallbackValue;
+    const rawDecision = value?.decision;
+    const decision: "allow" | "deny" | "allow_session" =
+      rawDecision === "allow" || rawDecision === "allow_session"
+        ? rawDecision
+        : "deny";
+
+    this._pending.delete(payload.message_id);
+    clearTimeout(entry.timeout);
+
+    if (decision === "allow_session") {
+      this._rememberSessionAllow(entry.session_id, entry.tool_name);
+    }
+
+    const outcome =
+      decision === "allow"
+        ? "allowed"
+        : decision === "allow_session"
+          ? "allowed_session"
+          : "denied";
+    await this._tryUpdateCard(
+      payload.channel_id,
+      payload.message_id,
+      buildPermissionResultCard({
+        tool_name: entry.tool_name,
+        outcome,
+        decided_by_open_id: payload.operator_open_id,
+      }),
+      "final-result",
+    );
+
+    this._logger.info(
+      {
+        request_id: entry.request_id,
+        session_id: entry.session_id,
+        tool_name: entry.tool_name,
+        decision,
+      },
+      "permission request decided",
+    );
+
+    entry.resolve({
+      behavior: decision === "deny" ? "deny" : "allow",
+      message:
+        decision === "deny" ? "Permission denied by the user." : undefined,
+      decided_by: "user",
+    });
+  }
+
+  /**
+   * Send an AskUserQuestion form to the initiator's chat and await the
+   * answers. On a malformed payload we deny with a hint so the tool call
+   * resolves instead of hanging; otherwise we store a pending entry keyed by
+   * the card's `message_id` and resolve when the user submits or the timeout
+   * fires.
+   */
+  private async _requestQuestion(
+    params: PermissionRequestParams,
+  ): Promise<PermissionDecision> {
+    const channel = this._feishuChannels.get(params.channel_id);
+    if (!channel) {
+      throw new Error(
+        `Question request for unknown channel_id=${params.channel_id}`,
+      );
+    }
+    const parsed = AskUserQuestionInput.safeParse(params.tool_input);
+    if (!parsed.success) {
+      this._logger.warn(
+        { session_id: params.session_id, issues: parsed.error.issues },
+        "malformed AskUserQuestion input, denying",
+      );
+      return {
+        behavior: "deny",
+        message:
+          "AskUserQuestion payload was malformed. Ask the user in plain text instead.",
+        decided_by: "user",
+      };
+    }
+    const questions = parsed.data.questions;
+    const requestId = uuid();
+    const card = buildQuestionCard({
+      request_id: requestId,
+      questions,
+      initiator_open_id: params.initiator_open_id,
+    });
+    const cardMessageId = await channel.sendRawCard(params.chat_id, card, {
+      replyTo: params.reply_to_message_id,
+      replyInThread: false,
+    });
+
+    return new Promise<PermissionDecision>((resolve) => {
+      const timeout = setTimeout(() => {
+        const entry = this._pendingQuestions.get(cardMessageId);
+        if (!entry) return;
+        this._pendingQuestions.delete(cardMessageId);
+        this._logger.warn(
+          { request_id: requestId, session_id: params.session_id },
+          "question request timed out, auto-denying",
+        );
+        void this._tryUpdateCard(
+          params.channel_id,
+          cardMessageId,
+          buildQuestionResultCard({ outcome: "timeout" }),
+          "question-timeout",
+        );
+        resolve({
+          behavior: "deny",
+          message: "Question timed out after 5 minutes with no answer.",
+          decided_by: "timeout",
+        });
+      }, this._timeoutMs);
+
+      this._pendingQuestions.set(cardMessageId, {
+        request_id: requestId,
+        session_id: params.session_id,
+        initiator_open_id: params.initiator_open_id,
+        channel_id: params.channel_id,
+        chat_id: params.chat_id,
+        card_message_id: cardMessageId,
+        questions,
+        created_at: Date.now(),
+        resolve,
+        timeout,
+      });
+      this._logger.info(
+        {
+          request_id: requestId,
+          session_id: params.session_id,
+          card_message_id: cardMessageId,
+          question_count: questions.length,
+        },
+        "question card sent",
+      );
+    });
+  }
+
+  /**
+   * Entry point invoked from the kernel's `card:action` listener when the
+   * payload's `action_name === QUESTION_ACTION` (the form's submit button).
+   * Maps `form_value` back to option labels; an incomplete submission
+   * re-renders the form with a warning instead of resolving.
+   */
+  async handleQuestionSubmit(payload: CardActionPayload): Promise<void> {
+    const channel = this._feishuChannels.get(payload.channel_id);
+    if (!channel) {
+      this._logger.warn(
+        { channel_id: payload.channel_id },
+        "question action for unknown channel",
+      );
+      return;
+    }
+    const entry = this._pendingQuestions.get(payload.message_id);
+    if (!entry) {
+      await this._tryUpdateCard(
+        payload.channel_id,
+        payload.message_id,
+        buildQuestionResultCard({ outcome: "already_answered" }),
+        "question-already-answered",
+      );
+      return;
+    }
+    if (entry.initiator_open_id !== payload.operator_open_id) {
+      // Keep the form intact for the initiator; the clicker just sees the
+      // generic Feishu ack. Mirrors the approve/deny card's behavior.
+      this._logger.info(
+        {
+          request_id: entry.request_id,
+          operator: payload.operator_open_id,
+          initiator: entry.initiator_open_id,
+        },
+        "non-initiator submit on question card; ignoring",
+      );
+      return;
+    }
+
+    const answers: Record<string, string | string[]> = {};
+    const detail: string[] = [];
+    const missing: string[] = [];
+    entry.questions.forEach((q, qi) => {
+      const heading = q.header?.trim() ? q.header.trim() : `问题 ${qi + 1}`;
+      if (q.multiSelect) {
+        const picked = q.options
+          .filter((_opt, oi) =>
+            _isTruthyChecker(payload.form_value[QUESTION_FIELD.checker(qi, oi)]),
+          )
+          .map((opt) => opt.label);
+        if (picked.length === 0) {
+          missing.push(heading);
+        } else {
+          answers[q.question] = picked;
+          detail.push(`- ${heading}：${picked.join("、")}`);
+        }
+      } else {
+        const raw = payload.form_value[QUESTION_FIELD.select(qi)];
+        const oi = typeof raw === "string" ? Number(raw) : Number.NaN;
+        const picked = Number.isInteger(oi) ? q.options[oi] : undefined;
+        if (picked) {
+          answers[q.question] = picked.label;
+          detail.push(`- ${heading}：${picked.label}`);
+        } else {
+          missing.push(heading);
+        }
+      }
+    });
+
+    if (missing.length > 0) {
+      // Re-render the form (selections reset client-side) with a warning;
+      // keep the pending entry and timeout alive for the retry.
+      await this._tryUpdateCard(
+        entry.channel_id,
+        entry.card_message_id,
+        buildQuestionCard({
+          request_id: entry.request_id,
+          questions: entry.questions,
+          initiator_open_id: entry.initiator_open_id,
+          warning: `请回答所有问题后再提交（待回答：${missing.join("、")}）`,
+        }),
+        "question-incomplete",
+      );
+      return;
+    }
+
+    this._pendingQuestions.delete(payload.message_id);
+    clearTimeout(entry.timeout);
+    await this._tryUpdateCard(
+      payload.channel_id,
+      payload.message_id,
+      buildQuestionResultCard({ outcome: "answered", detail }),
+      "question-answered",
+    );
+    this._logger.info(
+      { request_id: entry.request_id, session_id: entry.session_id },
+      "question answered",
+    );
+    entry.resolve({
+      behavior: "allow",
+      updated_input: { questions: entry.questions, answers },
+      decided_by: "user",
+    });
+  }
+
+  /**
+   * Mark every still-open permission and question card as expired and resolve
+   * its awaiting promise with a deny. Called on kernel shutdown: the agent
+   * subprocesses that long-poll for these decisions die with the kernel, so a
+   * card left untouched would look live yet never resolve. Best-effort — a
+   * failed card update is logged, not retried.
+   */
+  async expireAllPending(): Promise<void> {
+    const permissionEntries = [...this._pending.values()];
+    const questionEntries = [...this._pendingQuestions.values()];
+    this._pending.clear();
+    this._pendingQuestions.clear();
+
+    for (const entry of permissionEntries) {
+      clearTimeout(entry.timeout);
+      await this._tryUpdateCard(
+        entry.channel_id,
+        entry.card_message_id,
+        buildPermissionResultCard({
+          tool_name: entry.tool_name,
+          outcome: "expired",
+        }),
+        "shutdown-expire",
+      );
+      entry.resolve({
+        behavior: "deny",
+        message: "Kernel is shutting down; permission request expired.",
+        decided_by: "timeout",
+      });
+    }
+    for (const entry of questionEntries) {
+      clearTimeout(entry.timeout);
+      await this._tryUpdateCard(
+        entry.channel_id,
+        entry.card_message_id,
+        buildQuestionResultCard({ outcome: "expired" }),
+        "shutdown-expire",
+      );
+      entry.resolve({
+        behavior: "deny",
+        message: "Kernel is shutting down; question expired.",
+        decided_by: "timeout",
+      });
+    }
+    if (permissionEntries.length > 0 || questionEntries.length > 0) {
+      this._logger.info(
+        {
+          permission_cards: permissionEntries.length,
+          question_cards: questionEntries.length,
+        },
+        "expired open permission/question cards on shutdown",
+      );
+    }
+  }
+
+  /**
+   * Forget every tool remembered for the given session. Call on session
+   * teardown if you want to release memory eagerly; otherwise the map is
+   * cleared on the next kernel restart.
+   */
+  clearSession(sessionId: string): void {
+    this._sessionAllowlist.delete(sessionId);
+  }
+
+  private _isSessionAllowed(sessionId: string, toolName: string): boolean {
+    return this._sessionAllowlist.get(sessionId)?.has(toolName) === true;
+  }
+
+  private _rememberSessionAllow(sessionId: string, toolName: string): void {
+    let set = this._sessionAllowlist.get(sessionId);
+    if (!set) {
+      set = new Set();
+      this._sessionAllowlist.set(sessionId, set);
+    }
+    set.add(toolName);
+  }
+
+  /**
+   * Tag for the {@link PermissionFlow._handleCardAction} discriminator —
+   * exported so the kernel-level router can filter by `value.action`
+   * without re-deriving the string constant.
+   */
+  static readonly ACTION_NAME = PERMISSION_ACTION;
+
+  private async _tryUpdateCard(
+    channelId: string,
+    messageId: string,
+    card: ReturnType<typeof buildPermissionResultCard>,
+    stage: string,
+  ): Promise<void> {
+    const channel = this._feishuChannels.get(channelId);
+    if (!channel) return;
+    try {
+      await channel.updateRawCard(messageId, card);
+    } catch (err) {
+      this._logger.error(
+        { err, stage, message_id: messageId },
+        "permission updateRawCard failed",
+      );
+    }
+  }
+}
+
+/**
+ * Coerce a Feishu checker's echoed `form_value` entry to a boolean. Some
+ * clients send the literal boolean, others a string like `"true"`/`"on"`.
+ */
+function _isTruthyChecker(v: unknown): boolean {
+  if (v === true) return true;
+  if (typeof v === "string") {
+    const lower = v.toLowerCase();
+    return lower === "true" || lower === "1" || lower === "on";
+  }
+  return false;
+}
diff --git a/src/kernel/repo-ref.ts b/src/kernel/repo-ref.ts
new file mode 100644
index 0000000..90b76d1
--- /dev/null
+++ b/src/kernel/repo-ref.ts
@@ -0,0 +1,10 @@
+/**
+ * User-facing repo/branch label used across workspace cards and command
+ * results. Keep the separator centralized so copy stays consistent.
+ */
+export function formatRepoRef(
+  repo: string,
+  branch?: string | null,
+): string {
+  return branch ? `${repo}@${branch}` : repo;
+}
diff --git a/src/kernel/repos/index.ts b/src/kernel/repos/index.ts
new file mode 100644
index 0000000..7c47034
--- /dev/null
+++ b/src/kernel/repos/index.ts
@@ -0,0 +1,2 @@
+export { REPOS_ACTION, REPOS_FIELD } from "./repos-card";
+export { ReposFlow } from "./repos-flow";
diff --git a/src/kernel/repos/repos-card.ts b/src/kernel/repos/repos-card.ts
new file mode 100644
index 0000000..74b323e
--- /dev/null
+++ b/src/kernel/repos/repos-card.ts
@@ -0,0 +1,429 @@
+import type { PredefinedRepo } from "@/shared";
+
+import type {
+  ButtonElement,
+  Card,
+  ColumnSetElement,
+  Element,
+  FormElement,
+  InputElement,
+} from "../../community/feishu/messaging/types";
+import {
+  buildCardIntro,
+  buildDismissedCard,
+  buildMarkdown,
+  buildResultCard,
+  buildSectionBlock,
+} from "../setup/card-ui";
+
+/**
+ * Action discriminators for `/repos`. Kernel forwards any card action whose
+ * name starts with `repos_` to `ReposFlow.handleAction`.
+ */
+export const REPOS_ACTION = {
+  openAdd: "repos_open_add",
+  openEdit: "repos_open_edit",
+  openDelete: "repos_open_delete",
+  addSubmit: "repos_add_submit",
+  editSubmit: "repos_edit_submit",
+  deleteApply: "repos_delete_apply",
+  back: "repos_back",
+  dismiss: "repos_dismiss",
+} as const;
+
+/**
+ * Form field names for the add/edit forms. The two forms share input names
+ * so the submit handler can treat them uniformly — the discriminator is the
+ * button name (`addSubmit` vs `editSubmit`).
+ */
+export const REPOS_FIELD = {
+  name: "repo_name",
+  gitUrl: "repo_git_url",
+  description: "repo_description",
+} as const;
+
+export interface ReposMainCardOptions {
+  repos: PredefinedRepo[];
+  /** Path string surfaced in the subtitle so users know where the file lives. */
+  file_path: string;
+}
+
+/**
+ * Top-level `/repos` panel: lists every repo currently in `REPOS.md` with
+ * inline edit/delete buttons plus a "添加仓库" button at the bottom.
+ */
+export function buildReposMainCard(options: ReposMainCardOptions): Card {
+  const { repos, file_path } = options;
+  const elements: Element[] = [
+    buildCardIntro({
+      title: "REPOS.md 仓库管理",
+      subtitle: `${file_path} · ${repos.length} 个仓库`,
+    }),
+  ];
+
+  if (repos.length === 0) {
+    elements.push(
+      buildMarkdown(
+        "<font color='grey'>REPOS.md 里还没有任何仓库条目。点击下方「添加仓库」新增一个。</font>",
+      ),
+    );
+  } else {
+    for (const repo of repos) {
+      elements.push(_buildRepoRow(repo));
+    }
+  }
+
+  elements.push(_buildMainActionRow());
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: "📚 REPOS.md 管理" },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
+
+export interface ReposFormCardOptions {
+  /**
+   * Edit mode pre-fills the form with the current values and disables the
+   * `name` input (rename = delete + add). Add mode renders an empty form
+   * with the name input enabled.
+   */
+  mode: "add" | "edit";
+  initial?: PredefinedRepo;
+}
+
+/**
+ * Add / edit form card. Both modes share the same input layout — the
+ * submit button is the only thing that changes, so the handler can route
+ * on its name (`addSubmit` vs `editSubmit`).
+ */
+export function buildReposFormCard(options: ReposFormCardOptions): Card {
+  const { mode, initial } = options;
+  const title = mode === "add" ? "添加仓库" : `编辑仓库 ${initial?.name ?? ""}`;
+
+  const nameInput: InputElement = {
+    tag: "input",
+    name: REPOS_FIELD.name,
+    placeholder: { tag: "plain_text", content: "例如 agentara" },
+    default_value: initial?.name,
+    width: "fill",
+  };
+  const gitUrlInput: InputElement = {
+    tag: "input",
+    name: REPOS_FIELD.gitUrl,
+    placeholder: { tag: "plain_text", content: "git@... 或 https://..." },
+    default_value: initial?.git_url,
+    width: "fill",
+  };
+  const descInput: InputElement = {
+    tag: "input",
+    name: REPOS_FIELD.description,
+    placeholder: { tag: "plain_text", content: "一句话描述（可选）" },
+    default_value: initial?.description,
+    width: "fill",
+  };
+
+  const submitBtn: ButtonElement = {
+    tag: "button",
+    name:
+      mode === "add"
+        ? REPOS_ACTION.addSubmit
+        : REPOS_ACTION.editSubmit,
+    text: { tag: "plain_text", content: mode === "add" ? "保存" : "保存修改" },
+    type: "primary",
+    action_type: "form_submit",
+    width: "fill",
+  };
+
+  const formElements: Element[] = [
+    buildMarkdown("**名称**"),
+  ];
+  if (mode === "edit") {
+    // Renaming = delete + add, which would orphan any prose context inside
+    // the section. Surface the name as static text in edit mode to make
+    // that constraint obvious instead of pretending it's editable.
+    formElements.push(
+      buildMarkdown(`\`${initial?.name ?? ""}\``),
+      buildMarkdown(
+        "<font color='grey'>编辑模式下名称不可改；改名请先删除再添加。</font>",
+        { text_size: "notation" },
+      ),
+    );
+  } else {
+    formElements.push(nameInput);
+  }
+  formElements.push(
+    buildMarkdown("**git_url**"),
+    gitUrlInput,
+    buildMarkdown("**描述（可选）**"),
+    descInput,
+    submitBtn,
+  );
+
+  const form: FormElement = {
+    tag: "form",
+    name: mode === "add" ? "repos_add_form" : "repos_edit_form",
+    elements: formElements,
+  };
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: `📚 ${title}` },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements: [
+        buildCardIntro({ title }),
+        form,
+        _buildBackDismissRow(),
+      ],
+    },
+  };
+}
+
+export interface ReposDeleteConfirmCardOptions {
+  repo: PredefinedRepo;
+}
+
+export function buildReposDeleteConfirmCard(
+  options: ReposDeleteConfirmCardOptions,
+): Card {
+  const { repo } = options;
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: `⚠️ 删除 ${repo.name}` },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements: [
+        buildCardIntro({
+          title: "⚠️  确认删除仓库条目",
+          subtitle: repo.name,
+        }),
+        ...buildSectionBlock({
+          title: "将从 REPOS.md 移除",
+          lines: [
+            `- 名称：\`${repo.name}\``,
+            `- git_url：\`${repo.git_url}\``,
+            repo.description
+              ? `- 描述：${repo.description}`
+              : "- 描述：(未填)",
+            "- 已克隆的本地仓库不受影响。",
+          ],
+        }),
+        _buildDeleteConfirmRow(repo.name),
+      ],
+    },
+  };
+}
+
+export function buildReposResultCard(
+  summary: string,
+  detail: string[] = [],
+): Card {
+  const card = buildResultCard({
+    title: "REPOS.md",
+    summary,
+    detail,
+  });
+  card.body.elements.push(_buildBackDismissRow());
+  return card;
+}
+
+export function buildReposDismissedCard(): Card {
+  return buildDismissedCard({ title: "REPOS.md 仓库管理" });
+}
+
+function _buildRepoRow(repo: PredefinedRepo): ColumnSetElement {
+  const desc = repo.description?.trim();
+  const lines = [
+    `**${repo.name}**`,
+    `\`${repo.git_url}\``,
+  ];
+  if (desc) lines.push(`<font color='grey'>${desc}</font>`);
+
+  const editBtn: ButtonElement = {
+    tag: "button",
+    name: `repos_edit_btn_${repo.name}`,
+    text: { tag: "plain_text", content: "编辑" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: { action: REPOS_ACTION.openEdit, repo_name: repo.name },
+      },
+    ],
+  };
+  const deleteBtn: ButtonElement = {
+    tag: "button",
+    name: `repos_delete_btn_${repo.name}`,
+    text: { tag: "plain_text", content: "删除" },
+    type: "danger",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: { action: REPOS_ACTION.openDelete, repo_name: repo.name },
+      },
+    ],
+  };
+
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 3,
+        vertical_align: "center",
+        elements: [buildMarkdown(lines.join("\n"))],
+      },
+      {
+        tag: "column",
+        width: "170px",
+        vertical_align: "center",
+        elements: [
+          {
+            tag: "column_set",
+            flex_mode: "stretch",
+            horizontal_spacing: "4px",
+            columns: [
+              { tag: "column", width: "weighted", weight: 1, elements: [editBtn] },
+              { tag: "column", width: "weighted", weight: 1, elements: [deleteBtn] },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function _buildMainActionRow(): ColumnSetElement {
+  const addBtn: ButtonElement = {
+    tag: "button",
+    name: "repos_open_add_btn",
+    text: { tag: "plain_text", content: "添加仓库" },
+    type: "primary",
+    width: "fill",
+    behaviors: [
+      { type: "callback", value: { action: REPOS_ACTION.openAdd } },
+    ],
+  };
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      { tag: "column", width: "weighted", weight: 1, elements: [addBtn] },
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 1,
+        elements: [_buildDismissButton()],
+      },
+    ],
+  };
+}
+
+function _buildBackDismissRow(): ColumnSetElement {
+  const backBtn: ButtonElement = {
+    tag: "button",
+    name: "repos_back_btn",
+    text: { tag: "plain_text", content: "← 返回" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      { type: "callback", value: { action: REPOS_ACTION.back } },
+    ],
+  };
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      { tag: "column", width: "weighted", weight: 1, elements: [backBtn] },
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 1,
+        elements: [_buildDismissButton()],
+      },
+    ],
+  };
+}
+
+function _buildDeleteConfirmRow(repoName: string): ColumnSetElement {
+  const cancelBtn: ButtonElement = {
+    tag: "button",
+    name: "repos_delete_cancel_btn",
+    text: { tag: "plain_text", content: "← 返回" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      { type: "callback", value: { action: REPOS_ACTION.back } },
+    ],
+  };
+  const confirmBtn: ButtonElement = {
+    tag: "button",
+    name: "repos_delete_apply_btn",
+    text: { tag: "plain_text", content: "确认删除" },
+    type: "danger",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: { action: REPOS_ACTION.deleteApply, repo_name: repoName },
+      },
+    ],
+  };
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      { tag: "column", width: "weighted", weight: 1, elements: [cancelBtn] },
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 1,
+        elements: [_buildDismissButton()],
+      },
+      { tag: "column", width: "weighted", weight: 1, elements: [confirmBtn] },
+    ],
+  };
+}
+
+function _buildDismissButton(): ButtonElement {
+  return {
+    tag: "button",
+    name: "repos_dismiss_btn",
+    text: { tag: "plain_text", content: "关闭" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      { type: "callback", value: { action: REPOS_ACTION.dismiss } },
+    ],
+  };
+}
diff --git a/src/kernel/repos/repos-flow.ts b/src/kernel/repos/repos-flow.ts
new file mode 100644
index 0000000..0ccc58c
--- /dev/null
+++ b/src/kernel/repos/repos-flow.ts
@@ -0,0 +1,374 @@
+import type { Logger } from "@/shared";
+import {
+  config,
+  createLogger,
+  loadPredefinedRepos,
+  type CardActionPayload,
+  type PredefinedRepo,
+  type UserMessage,
+} from "@/shared";
+
+import type { FeishuMessageChannel } from "../../community/feishu/messaging/message-channel";
+import type { Card } from "../../community/feishu/messaging/types";
+
+import {
+  buildReposDeleteConfirmCard,
+  buildReposDismissedCard,
+  buildReposFormCard,
+  buildReposMainCard,
+  buildReposResultCard,
+  REPOS_ACTION,
+  REPOS_FIELD,
+} from "./repos-card";
+import { addRepo, editRepo, removeRepo } from "./repos-writer";
+
+/**
+ * Stateful orchestrator for the `/repos` interactive flow.
+ *
+ * Like `/setting`, this flow doesn't track pending cards in memory — every
+ * card-action payload that needs context (edit/delete target) carries the
+ * `repo_name` it applies to, so handlers can re-read REPOS.md and operate
+ * statelessly. A stale card from before a restart simply re-reads the
+ * latest file state on the next click.
+ */
+export class ReposFlow {
+  private readonly _logger: Logger = createLogger("repos-flow");
+  private readonly _feishuChannels: Map<string, FeishuMessageChannel>;
+
+  constructor(deps: {
+    feishuChannels: Map<string, FeishuMessageChannel>;
+  }) {
+    this._feishuChannels = deps.feishuChannels;
+  }
+
+  /** Entry point for `/repos`. */
+  async start(message: UserMessage): Promise<void> {
+    const chatId = message.chat_id;
+    if (!chatId || !message.channel_id) {
+      await this._replyText(message, "❌ /repos 需要飞书会话上下文。");
+      return;
+    }
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) {
+      await this._replyText(message, "❌ 无法找到对应的飞书 channel。");
+      return;
+    }
+    const card = this._renderMainCard();
+    try {
+      await channel.sendRawCard(chatId, card, {
+        replyTo: message.id,
+        replyInThread: false,
+      });
+    } catch (err) {
+      this._logger.error(
+        { err, chat_id: chatId },
+        "failed to send repos main card",
+      );
+      await this._replyText(
+        message,
+        `❌ 渲染 /repos 卡片失败：${(err as Error).message}`,
+      );
+    }
+  }
+
+  /** Single entry point for every `repos_*` card action. */
+  async handleAction(payload: CardActionPayload): Promise<void> {
+    const channel = this._feishuChannels.get(payload.channel_id);
+    if (!channel) {
+      this._logger.warn(
+        { channel_id: payload.channel_id, action_name: payload.action_name },
+        "repos action for unknown channel",
+      );
+      return;
+    }
+    try {
+      switch (payload.action_name) {
+        case REPOS_ACTION.openAdd:
+          await this._tryUpdateCard(
+            channel,
+            payload.message_id,
+            buildReposFormCard({ mode: "add" }),
+            "open-add",
+          );
+          return;
+        case REPOS_ACTION.openEdit:
+          await this._handleOpenEdit(channel, payload);
+          return;
+        case REPOS_ACTION.openDelete:
+          await this._handleOpenDelete(channel, payload);
+          return;
+        case REPOS_ACTION.addSubmit:
+          await this._handleAddSubmit(channel, payload);
+          return;
+        case REPOS_ACTION.editSubmit:
+          await this._handleEditSubmit(channel, payload);
+          return;
+        case REPOS_ACTION.deleteApply:
+          await this._handleDeleteApply(channel, payload);
+          return;
+        case REPOS_ACTION.back:
+          await this._tryUpdateCard(
+            channel,
+            payload.message_id,
+            this._renderMainCard(),
+            "back",
+          );
+          return;
+        case REPOS_ACTION.dismiss:
+          await this._tryUpdateCard(
+            channel,
+            payload.message_id,
+            buildReposDismissedCard(),
+            "dismiss",
+          );
+          return;
+        default:
+          this._logger.warn(
+            { action_name: payload.action_name },
+            "unknown repos action",
+          );
+      }
+    } catch (err) {
+      this._logger.error(
+        { err, action_name: payload.action_name },
+        "repos action failed",
+      );
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard(`❌ 操作失败：${(err as Error).message}`),
+        "action-error",
+      );
+    }
+  }
+
+  private async _handleOpenEdit(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const repoName = _readRepoName(payload);
+    if (!repoName) return;
+    const repo = _findRepo(repoName);
+    if (!repo) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard(`⚠️  仓库 \`${repoName}\` 已不存在。`),
+        "edit-missing",
+      );
+      return;
+    }
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildReposFormCard({ mode: "edit", initial: repo }),
+      "open-edit",
+    );
+  }
+
+  private async _handleOpenDelete(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const repoName = _readRepoName(payload);
+    if (!repoName) return;
+    const repo = _findRepo(repoName);
+    if (!repo) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard(`⚠️  仓库 \`${repoName}\` 已不存在。`),
+        "delete-missing",
+      );
+      return;
+    }
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildReposDeleteConfirmCard({ repo }),
+      "open-delete",
+    );
+  }
+
+  private async _handleAddSubmit(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const name = _readField(payload, REPOS_FIELD.name).trim();
+    const gitUrl = _readField(payload, REPOS_FIELD.gitUrl).trim();
+    const description = _readField(payload, REPOS_FIELD.description).trim();
+    if (!name || !gitUrl) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard("❌ 名称和 git_url 都不能为空。"),
+        "add-invalid",
+      );
+      return;
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(name)) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard(
+          `❌ 名称 \`${name}\` 不合法，只允许字母、数字、\`.\`、\`_\`、\`-\`。`,
+        ),
+        "add-invalid-name",
+      );
+      return;
+    }
+    const result = addRepo({ name, git_url: gitUrl, description });
+    if (!result.ok) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard(`❌ ${result.reason ?? "写入失败"}`),
+        "add-failed",
+      );
+      return;
+    }
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildReposResultCard(
+        `✅ 已添加 \`${name}\`。`,
+        [
+          `- git_url：\`${gitUrl}\``,
+          description ? `- 描述：${description}` : "- 描述：(未填)",
+        ],
+      ),
+      "add-ok",
+    );
+    this._logger.info({ name, git_url: gitUrl }, "repos: added");
+  }
+
+  private async _handleEditSubmit(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const name = _readField(payload, REPOS_FIELD.name).trim();
+    const gitUrl = _readField(payload, REPOS_FIELD.gitUrl).trim();
+    const description = _readField(payload, REPOS_FIELD.description).trim();
+    if (!name) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard("❌ 未能识别要编辑的仓库名。"),
+        "edit-missing-name",
+      );
+      return;
+    }
+    if (!gitUrl) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard("❌ git_url 不能为空。"),
+        "edit-invalid",
+      );
+      return;
+    }
+    const result = editRepo(name, { git_url: gitUrl, description });
+    if (!result.ok) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard(`❌ ${result.reason ?? "写入失败"}`),
+        "edit-failed",
+      );
+      return;
+    }
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildReposResultCard(
+        `✅ 已更新 \`${name}\`。`,
+        [
+          `- git_url：\`${gitUrl}\``,
+          description ? `- 描述：${description}` : "- 描述：(未填)",
+        ],
+      ),
+      "edit-ok",
+    );
+    this._logger.info({ name, git_url: gitUrl }, "repos: edited");
+  }
+
+  private async _handleDeleteApply(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const repoName = _readRepoName(payload);
+    if (!repoName) return;
+    const result = removeRepo(repoName);
+    if (!result.ok) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildReposResultCard(`❌ ${result.reason ?? "删除失败"}`),
+        "delete-failed",
+      );
+      return;
+    }
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildReposResultCard(`✅ 已删除 \`${repoName}\`。`),
+      "delete-ok",
+    );
+    this._logger.info({ name: repoName }, "repos: removed");
+  }
+
+  private _renderMainCard(): Card {
+    return buildReposMainCard({
+      repos: loadPredefinedRepos(),
+      file_path: config.paths.repos_md,
+    });
+  }
+
+  private async _tryUpdateCard(
+    channel: FeishuMessageChannel,
+    messageId: string,
+    card: Card,
+    stage: string,
+  ): Promise<void> {
+    try {
+      await channel.updateRawCard(messageId, card);
+    } catch (err) {
+      this._logger.error(
+        { err, stage, message_id: messageId },
+        "repos updateRawCard failed",
+      );
+    }
+  }
+
+  private async _replyText(
+    message: UserMessage,
+    text: string,
+  ): Promise<void> {
+    if (!message.channel_id) return;
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) return;
+    await channel.replyMessage(
+      message.id,
+      {
+        role: "assistant",
+        session_id: message.session_id,
+        content: [{ type: "text", text }],
+      },
+      { streaming: false, replyInThread: false },
+    );
+  }
+}
+
+function _readRepoName(payload: CardActionPayload): string | null {
+  const name = payload.value.repo_name;
+  return typeof name === "string" && name ? name : null;
+}
+
+function _readField(payload: CardActionPayload, key: string): string {
+  const raw = payload.form_value[key];
+  return typeof raw === "string" ? raw : "";
+}
+
+function _findRepo(name: string): PredefinedRepo | null {
+  return loadPredefinedRepos().find((r) => r.name === name) ?? null;
+}
diff --git a/src/kernel/repos/repos-writer.ts b/src/kernel/repos/repos-writer.ts
new file mode 100644
index 0000000..7417377
--- /dev/null
+++ b/src/kernel/repos/repos-writer.ts
@@ -0,0 +1,166 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+import { config } from "@/shared";
+
+/**
+ * Boundary of a single `## <name>` section in `REPOS.md`. `start` is the
+ * 0-based line index of the heading itself; `end` is the line index AFTER
+ * the section (i.e. the next H2 line or `lines.length`). Sections nested
+ * inside `<!-- ... -->` blocks are skipped by `findSection` — only real
+ * repo entries are mutated.
+ */
+interface SectionRange {
+  start: number;
+  end: number;
+}
+
+/**
+ * Inputs for `addRepo` / `editRepo`. `description` is optional — REPOS.md
+ * allows missing description bullets.
+ */
+export interface RepoInput {
+  name: string;
+  git_url: string;
+  description?: string;
+}
+
+export interface WriteResult {
+  ok: boolean;
+  reason?: string;
+}
+
+/**
+ * Append a new repo section to `REPOS.md`. Fails fast when a section with
+ * the same name already exists so the user has to delete it first instead
+ * of silently overwriting context they accumulated under the existing
+ * heading.
+ */
+export function addRepo(input: RepoInput): WriteResult {
+  const raw = _readFile();
+  if (_findSection(raw, input.name)) {
+    return { ok: false, reason: `仓库 \`${input.name}\` 已存在，请先编辑或删除。` };
+  }
+  const trimmed = raw.replace(/\s+$/, "");
+  const block = _formatSection(input);
+  const next = trimmed.length > 0 ? `${trimmed}\n\n${block}\n` : `${block}\n`;
+  writeFileSync(config.paths.repos_md, next, "utf-8");
+  return { ok: true };
+}
+
+/**
+ * Update the `git_url` and/or `description` bullets of an existing section.
+ * Non-bullet content (free-form agent context) inside the section is
+ * preserved verbatim — only the two structured bullet lines are touched.
+ * Returns `{ ok: false }` when the section doesn't exist.
+ */
+export function editRepo(
+  name: string,
+  patch: { git_url?: string; description?: string },
+): WriteResult {
+  const raw = _readFile();
+  const range = _findSection(raw, name);
+  if (!range) {
+    return { ok: false, reason: `仓库 \`${name}\` 不存在。` };
+  }
+  const lines = raw.split(/\r?\n/);
+  const section = lines.slice(range.start, range.end);
+  let gitTouched = false;
+  let descTouched = false;
+  for (let i = 0; i < section.length; i += 1) {
+    const line = section[i]!;
+    if (patch.git_url !== undefined && /^\s*-\s*git_url\s*:/.test(line)) {
+      section[i] = `- git_url: ${patch.git_url}`;
+      gitTouched = true;
+    }
+    if (patch.description !== undefined && /^\s*-\s*description\s*:/.test(line)) {
+      section[i] = `- description: ${patch.description}`;
+      descTouched = true;
+    }
+  }
+  // Bullets that didn't exist before get appended right after the heading
+  // so they land at the canonical spot for the next read.
+  const headerIdx = 0;
+  const insertions: string[] = [];
+  if (patch.git_url !== undefined && !gitTouched) {
+    insertions.push(`- git_url: ${patch.git_url}`);
+  }
+  if (patch.description !== undefined && !descTouched) {
+    insertions.push(`- description: ${patch.description}`);
+  }
+  if (insertions.length > 0) {
+    section.splice(headerIdx + 1, 0, "", ...insertions);
+  }
+  const next = [
+    ...lines.slice(0, range.start),
+    ...section,
+    ...lines.slice(range.end),
+  ].join("\n");
+  writeFileSync(config.paths.repos_md, next, "utf-8");
+  return { ok: true };
+}
+
+/**
+ * Remove a section in its entirety. Trailing whitespace between adjacent
+ * sections is collapsed so the file stays tidy across repeated edits.
+ */
+export function removeRepo(name: string): WriteResult {
+  const raw = _readFile();
+  const range = _findSection(raw, name);
+  if (!range) {
+    return { ok: false, reason: `仓库 \`${name}\` 不存在。` };
+  }
+  const lines = raw.split(/\r?\n/);
+  const next = [
+    ...lines.slice(0, range.start),
+    ...lines.slice(range.end),
+  ]
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n");
+  writeFileSync(config.paths.repos_md, next, "utf-8");
+  return { ok: true };
+}
+
+function _readFile(): string {
+  if (!existsSync(config.paths.repos_md)) return "";
+  return readFileSync(config.paths.repos_md, "utf-8");
+}
+
+function _formatSection(repo: RepoInput): string {
+  const desc = repo.description?.trim();
+  const bullets = [`- git_url: ${repo.git_url}`];
+  if (desc) bullets.push(`- description: ${desc}`);
+  return [`## ${repo.name}`, "", ...bullets].join("\n");
+}
+
+/**
+ * Locate a section by name while ignoring H2 headings that live inside
+ * `<!-- ... -->` comment blocks. Mirrors the comment-skipping logic in
+ * `loadPredefinedRepos` so writer and reader stay in lockstep.
+ */
+function _findSection(raw: string, name: string): SectionRange | null {
+  const lines = raw.split(/\r?\n/);
+  const target = name.trim();
+  let inHtmlComment = false;
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i]!;
+    if (inHtmlComment) {
+      if (line.includes("-->")) inHtmlComment = false;
+      continue;
+    }
+    if (line.trim().startsWith("<!--") && !line.includes("-->")) {
+      inHtmlComment = true;
+      continue;
+    }
+    const h2 = /^##\s+(.+?)\s*$/.exec(line);
+    if (!h2) continue;
+    if (start === -1) {
+      if (h2[1]!.trim() === target) start = i;
+      continue;
+    }
+    // Second H2 (after we've found ours) terminates the section.
+    return { start, end: i };
+  }
+  if (start === -1) return null;
+  return { start, end: lines.length };
+}
diff --git a/src/kernel/sessioning/data/schema.ts b/src/kernel/sessioning/data/schema.ts
index 9010435..c7b1aee 100644
--- a/src/kernel/sessioning/data/schema.ts
+++ b/src/kernel/sessioning/data/schema.ts
@@ -1,4 +1,4 @@
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";
 
 /**
  * Persisted session records that track session metadata across restarts.
@@ -15,6 +15,10 @@ export const sessions = sqliteTable("sessions", {
   cwd: text("cwd").notNull(),
   /** The channel id this session belongs to, or null for legacy sessions. */
   channel_id: text("channel_id"),
+  /** Feishu chat_id owning this session. Null for non-Feishu or legacy. */
+  chat_id: text("chat_id"),
+  /** Feishu topic/thread id for this session. Null for non-threaded. */
+  thread_id: text("thread_id"),
   /** The text content of the session's first inbound message. */
   first_message: text("first_message").notNull().default(""),
   /** Runner-specific session/thread id (e.g. Codex thread id) for resume. */
@@ -28,3 +32,61 @@ export const sessions = sqliteTable("sessions", {
   /** Epoch milliseconds when the session was last updated. */
   updated_at: integer("updated_at").notNull(),
 });
+
+/**
+ * Persisted workspace registry. A workspace has its own stable id so multiple
+ * Feishu groups can bind to the same underlying directory while preserving a
+ * human-readable name/path for display.
+ *
+ * `active_repo` and `active_branch` live here (not on the binding) because
+ * only one `.git/HEAD` exists per cloned repo — the "active" state is a
+ * property of the workspace on disk, shared by any group bound to it.
+ */
+export const workspaces = sqliteTable(
+  "workspaces",
+  {
+    /** Stable workspace id used by `/bind <workspace-id>`. */
+    id: text("id").primaryKey(),
+    /** Human-readable workspace name (also the directory basename today). */
+    name: text("name").notNull(),
+    /** Absolute path of the workspace root on disk. */
+    path: text("path").notNull(),
+    /** Basename of the currently focused repo under `path`, or null. */
+    active_repo: text("active_repo"),
+    /** Git branch to check out in the active repo on dispatch, or null. */
+    active_branch: text("active_branch"),
+    /** Epoch milliseconds when the workspace was created. */
+    created_at: integer("created_at").notNull(),
+    /** Epoch milliseconds when the workspace was last updated. */
+    updated_at: integer("updated_at").notNull(),
+    /**
+     * Epoch milliseconds of the last time any chat bound to this workspace
+     * dispatched a message, re-bound, or mutated active state. Distinct from
+     * `updated_at` (which only moves on explicit row writes): this tracks
+     * usage, so the `/setting` panel can surface dormant workspaces.
+     */
+    last_active_at: integer("last_active_at").notNull(),
+  },
+  (table) => ({
+    path_unique: uniqueIndex("workspaces_path_unique").on(table.path),
+  }),
+);
+
+/**
+ * Persisted group↔workspace bindings. One row per Feishu group that has been
+ * bound via `/bind` or `/setup`. Absence of a row means the group is unbound
+ * and falls back to the default workspace.
+ *
+ * The binding is a thin many-to-one pointer — active repo/branch belong to
+ * the workspace itself, so groups bound to the same workspace share them.
+ */
+export const groupWorkspaces = sqliteTable("group_workspaces", {
+  /** Feishu chat id. */
+  chat_id: text("chat_id").primaryKey(),
+  /** Stable workspace id. */
+  workspace_id: text("workspace_id").notNull(),
+  /** Epoch milliseconds when the binding was created. */
+  created_at: integer("created_at").notNull(),
+  /** Epoch milliseconds when the binding was last updated. */
+  updated_at: integer("updated_at").notNull(),
+});
diff --git a/src/kernel/sessioning/session-manager.ts b/src/kernel/sessioning/session-manager.ts
index 77fdcd4..3dfe575 100644
--- a/src/kernel/sessioning/session-manager.ts
+++ b/src/kernel/sessioning/session-manager.ts
@@ -1,11 +1,19 @@
 import { existsSync, unlinkSync } from "node:fs";
 
-import { and, desc, eq, isNull } from "drizzle-orm";
+import { and, desc, eq } from "drizzle-orm";
 
 import type { DrizzleDB } from "@/data";
-import { config, createLogger, extractTextContent, uuid } from "@/shared";
+import {
+  config,
+  createLogger,
+  extractTextContent,
+  inlineMentions,
+  uuid,
+} from "@/shared";
 import type { Session as SessionEntity, UserMessage } from "@/shared";
 
+import { getRuntimeDefaultAgentType, resolveAgentTypeAlias } from "../agents";
+
 import { sessions } from "./data";
 import { Session } from "./session";
 import {
@@ -21,7 +29,7 @@ import {
 export interface SessionResolveOptions {
   /**
    * The type of agent runner (e.g. "claude-code").
-   * Defaults to `config.agents.default.type`.
+   * Defaults to the runtime default agent type.
    */
   agentType?: string;
 
@@ -36,6 +44,28 @@ export interface SessionResolveOptions {
    */
   channelId?: string;
 
+  /**
+   * Feishu chat_id for this session. Stored on create, not used on resume.
+   */
+  chatId?: string | null;
+
+  /**
+   * Feishu thread/topic id for this session. Stored on create, not used on resume.
+   */
+  threadId?: string | null;
+
+  /**
+   * Extra env vars to pass into the runner spawn (e.g. DEV_ASSETS_PRIMARY_REPO).
+   * Not persisted; re-resolved on every dispatch from group binding.
+   */
+  envExtras?: Record<string, string>;
+
+  /**
+   * Resume the Agentara session row but start a fresh underlying runner
+   * session/thread. Used when a provider-specific resume id is stale.
+   */
+  forceNewRunnerSession?: boolean;
+
   /**
    * The first message of the session.
    */
@@ -79,7 +109,7 @@ export class SessionManager {
   /**
    * Resolves session by database existence: creates if missing, resumes if exists.
    * @param sessionId - The session identifier.
-   * @param options - Optional agent_type and cwd (default from config).
+   * @param options - Optional agent_type and cwd (default from runtime/config).
    * @returns A Session instance.
    */
   async resolveSession(
@@ -95,7 +125,7 @@ export class SessionManager {
   /**
    * Creates a new session and inserts a row into the database.
    * @param sessionId - The session identifier.
-   * @param options - Optional agent_type and cwd (default from config).
+   * @param options - Optional agent_type and cwd (default from runtime/config).
    * @returns A Session instance with isNewSession: true.
    * @throws SessionAlreadyExistsError if the session already exists.
    */
@@ -107,9 +137,13 @@ export class SessionManager {
       throw new SessionAlreadyExistsError(sessionId);
     }
 
-    const agentType = options?.agentType ?? config.agents.default.type;
+    const requestedAgentType = options?.agentType ?? getRuntimeDefaultAgentType();
+    const agentType = resolveAgentTypeAlias(requestedAgentType);
     const cwd = options?.cwd ?? config.paths.home;
     const channelId = options?.channelId ?? null;
+    const chatId = options?.chatId ?? null;
+    const threadId = options?.threadId ?? null;
+    const envExtras = options?.envExtras;
     const now = Date.now();
 
     this._db
@@ -119,6 +153,8 @@ export class SessionManager {
         agent_type: agentType,
         cwd,
         channel_id: channelId,
+        chat_id: chatId,
+        thread_id: threadId,
         last_message_created_at: null,
         runner_session_id: null,
         created_at: now,
@@ -129,14 +165,28 @@ export class SessionManager {
     if (options?.firstMessage) {
       this._updateFirstMessage(
         sessionId,
-        extractTextContent(options.firstMessage),
+        inlineMentions(
+          extractTextContent(options.firstMessage),
+          options.firstMessage.mentions,
+        ),
       );
     }
 
+    if (agentType !== requestedAgentType) {
+      this._logger.info(
+        {
+          session_id: sessionId,
+          requested_agent_type: requestedAgentType,
+          resolved_agent_type: agentType,
+        },
+        "legacy agent type resolved for new session",
+      );
+    }
     this._logger.info(`Creating session: ${sessionId}`);
     const session = new Session(sessionId, agentType, {
       isNewSession: true,
       cwd,
+      envExtras,
       runnerSessionId: undefined,
     });
     this._attachWriter(session, sessionId);
@@ -215,14 +265,29 @@ export class SessionManager {
       throw new SessionNotFoundError(sessionId);
     }
 
+    const requestedAgentType = options?.agentType ?? row.agent_type;
+    const agentType = resolveAgentTypeAlias(requestedAgentType);
+    if (agentType !== requestedAgentType) {
+      this._logger.info(
+        {
+          session_id: sessionId,
+          requested_agent_type: requestedAgentType,
+          resolved_agent_type: agentType,
+        },
+        "legacy agent type resolved for resumed session",
+      );
+    }
     this._logger.info(`Resuming session: ${sessionId}`);
     const session = new Session(
       sessionId,
-      options?.agentType ?? row.agent_type,
+      agentType,
       {
-        isNewSession: false,
+        isNewSession: options?.forceNewRunnerSession ?? false,
         cwd: options?.cwd ?? row.cwd,
-        runnerSessionId: row.runner_session_id ?? undefined,
+        envExtras: options?.envExtras,
+        runnerSessionId: options?.forceNewRunnerSession
+          ? undefined
+          : row.runner_session_id ?? undefined,
       },
     );
     this._attachWriter(session, sessionId);
@@ -244,6 +309,20 @@ export class SessionManager {
       .map((row) => this._toSessionEntity(row));
   }
 
+  /**
+   * Returns the persisted session row, or undefined if not found. Read-only
+   * accessor for commands that need to surface session metadata
+   * (e.g. `/topic` shows agent_type and runner_session_id).
+   */
+  getSession(sessionId: string): SessionEntity | undefined {
+    const row = this._db
+      .select()
+      .from(sessions)
+      .where(eq(sessions.id, sessionId))
+      .get();
+    return row ? this._toSessionEntity(row) : undefined;
+  }
+
   /**
    * Removes a session: deletes the database record and the associated JSONL file.
    * @param sessionId - The session identifier.
@@ -261,6 +340,17 @@ export class SessionManager {
     this._logger.info(`Removed session: ${sessionId}`);
   }
 
+  resetRunnerSessionId(sessionId: string): void {
+    this._db
+      .update(sessions)
+      .set({
+        runner_session_id: null,
+        updated_at: Date.now(),
+      })
+      .where(eq(sessions.id, sessionId))
+      .run();
+  }
+
   /**
    * Updates the `last_message_created_at` and `updated_at` timestamps for a session.
    * @param sessionId - The session identifier.
@@ -301,9 +391,7 @@ export class SessionManager {
         runner_session_id: runnerSessionId,
         updated_at: Date.now(),
       })
-      .where(
-        and(eq(sessions.id, sessionId), isNull(sessions.runner_session_id)),
-      )
+      .where(eq(sessions.id, sessionId))
       .run();
   }
 
diff --git a/src/kernel/sessioning/writers/session-log-writer.ts b/src/kernel/sessioning/writers/session-log-writer.ts
index 7df2d95..4a416eb 100644
--- a/src/kernel/sessioning/writers/session-log-writer.ts
+++ b/src/kernel/sessioning/writers/session-log-writer.ts
@@ -1,6 +1,7 @@
 import {
   createLogger,
   extractTextContent,
+  inlineMentions,
   type Logger,
   type Message,
 } from "@/shared";
@@ -27,7 +28,9 @@ export class SessionLogWriter implements SessionWriter {
         this._logger.debug(`SYSTEM: ${message.subtype}`);
         break;
       case "user":
-        this._logger.debug(`USER: ${extractTextContent(message)}`);
+        this._logger.debug(
+          `USER: ${inlineMentions(extractTextContent(message), message.mentions)}`,
+        );
         break;
       case "assistant":
         this._logger.debug(
diff --git a/src/kernel/sessioning/writers/session-writer-utils.ts b/src/kernel/sessioning/writers/session-writer-utils.ts
index 3cb2136..e17f72b 100644
--- a/src/kernel/sessioning/writers/session-writer-utils.ts
+++ b/src/kernel/sessioning/writers/session-writer-utils.ts
@@ -9,6 +9,7 @@ import { dirname } from "node:path";
 import {
   logger,
   extractTextContent,
+  inlineMentions,
   isPureTextMessage,
   type Message,
 } from "@/shared";
@@ -52,6 +53,8 @@ export function formatFileLine(message: Message): string | null {
   if (!isPureTextMessage(message)) {
     return null;
   }
-  const text = extractTextContent(message);
+  const raw = extractTextContent(message);
+  const text =
+    message.role === "user" ? inlineMentions(raw, message.mentions) : raw;
   return `${message.role.toUpperCase()}:\n${text}`;
 }
diff --git a/src/kernel/setting/config-writer.ts b/src/kernel/setting/config-writer.ts
new file mode 100644
index 0000000..f448c3b
--- /dev/null
+++ b/src/kernel/setting/config-writer.ts
@@ -0,0 +1,87 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+import { config, createLogger, reloadConfig } from "@/shared";
+
+const _logger = createLogger("config-writer");
+
+/**
+ * Partial shape of the editable slice of `config.yaml`. Kept deliberately
+ * narrow — only the fields exposed by the `/setting` panel land here. Fields
+ * not present in the patch are left untouched on disk.
+ */
+export interface SettingConfigPatch {
+  timezone?: string;
+  agents?: {
+    default?: {
+      type?: string;
+      /** Empty string clears the key so the runner uses its own default. */
+      model?: string;
+    };
+    codex?: {
+      isolate_host_env?: boolean;
+    };
+  };
+  tasking?: {
+    max_retries?: number;
+  };
+}
+
+/**
+ * Read `$AGENTARA_HOME/config.yaml`, deep-merge the patch, write it back,
+ * then reload the in-memory `config` singleton. Throws on YAML/IO errors —
+ * callers should surface the failure on the result card.
+ */
+export function writeConfigPatch(patch: SettingConfigPatch): void {
+  const path = join(config.paths.home, "config.yaml");
+  const raw = readFileSync(path, "utf-8");
+  const parsed = (parseYaml(raw) as Record<string, unknown> | null) ?? {};
+  const merged = _deepMerge(parsed, patch as Record<string, unknown>);
+  _applyClears(merged);
+  writeFileSync(path, stringifyYaml(merged));
+  reloadConfig();
+  _logger.info({ patch }, "config.yaml updated");
+}
+
+function _isPlainObject(v: unknown): v is Record<string, unknown> {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    Object.getPrototypeOf(v) === Object.prototype
+  );
+}
+
+function _deepMerge(
+  base: Record<string, unknown>,
+  patch: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, patchVal] of Object.entries(patch)) {
+    if (patchVal === undefined) continue;
+    const baseVal = out[key];
+    if (_isPlainObject(baseVal) && _isPlainObject(patchVal)) {
+      out[key] = _deepMerge(baseVal, patchVal);
+    } else {
+      out[key] = patchVal;
+    }
+  }
+  return out;
+}
+
+/**
+ * Empty-string sentinel means "clear the field" — `agents.default.model` is
+ * optional in the Zod schema, and forcing an empty string through would break
+ * runners that treat "" as a real model id.
+ */
+function _applyClears(merged: Record<string, unknown>): void {
+  const agents = merged.agents;
+  if (_isPlainObject(agents)) {
+    const def = agents.default;
+    if (_isPlainObject(def) && def.model === "") {
+      delete def.model;
+    }
+  }
+}
diff --git a/src/kernel/setting/setting-card.ts b/src/kernel/setting/setting-card.ts
new file mode 100644
index 0000000..2a6c0a8
--- /dev/null
+++ b/src/kernel/setting/setting-card.ts
@@ -0,0 +1,674 @@
+import dayjs from "dayjs";
+
+import { formatRepoRef } from "@/kernel/repo-ref";
+import type { GroupWorkspace, Workspace } from "@/shared";
+
+import type {
+  ButtonElement,
+  Card,
+  CheckerElement,
+  ColumnSetElement,
+  Element,
+  FormElement,
+  InputElement,
+  SelectStaticElement,
+} from "../../community/feishu/messaging/types";
+import {
+  buildCardIntro,
+  buildDismissedCard,
+  buildMarkdown,
+  buildResultCard,
+  buildSectionBlock,
+} from "../setup/card-ui";
+
+/**
+ * Action discriminators for every interactive element on `/setting` cards.
+ * `setting_save_config` is a form_submit button (Feishu echoes the button
+ * name as `action_name`); the rest are callback buttons whose `value.action`
+ * drives routing. All names share the `setting_` prefix so the kernel can
+ * forward them to the flow with a single `startsWith` check.
+ */
+export const SETTING_ACTION = {
+  saveConfig: "setting_save_config",
+  mainBack: "setting_main_back",
+  wsDetail: "setting_ws_detail",
+  wsDeletePrompt: "setting_ws_delete_prompt",
+  wsDeleteApply: "setting_ws_delete_apply",
+  dismiss: "setting_dismiss",
+} as const;
+
+/**
+ * Form field names for the global-config section of the main card. Shared
+ * between renderer and submit handler so the two cannot drift.
+ */
+export const SETTING_FIELD = {
+  agentType: "agent_type",
+  agentModel: "agent_model",
+  codexIsolateHostEnv: "codex_isolate_host_env",
+  maxRetries: "max_retries",
+} as const;
+
+/**
+ * Snapshot of everything the main card needs to render. Flow resolves these
+ * once per render and passes them in; the card file stays pure.
+ */
+export interface SettingMainCardOptions {
+  agent: {
+    active_type: string;
+    available_types: string[];
+  };
+  config_values: {
+    agent_model: string;
+    codex_isolate_host_env: boolean;
+    max_retries: number;
+  };
+  workspaces: Array<{
+    workspace: Workspace;
+    binding_count: number;
+    is_current: boolean;
+    /** `_default` and similar reserved paths skip the delete button. */
+    is_protected: boolean;
+    /**
+     * Live branch name the workspace's active repo is currently on (from the
+     * on-disk HEAD). `null` when there's no active_repo or HEAD is detached.
+     * Resolved by the flow so the card never displays the stale stored
+     * `active_branch` hint.
+     */
+    active_branch_head: string | null;
+  }>;
+  current_chat_id?: string | null;
+}
+
+/**
+ * Top-level `/setting` panel: a global-config form on top, a workspace list
+ * beneath. Each workspace row has a "详情" callback button that swaps the
+ * card for a detail view in place via `updateRawCard`.
+ */
+export function buildSettingMainCard(options: SettingMainCardOptions): Card {
+  const elements: Element[] = [
+    buildCardIntro({
+      title: "设置面板",
+      subtitle: "全局运行时 + workspace 管理",
+    }),
+    _buildConfigForm(options),
+    buildMarkdown("**Workspace 管理**"),
+  ];
+
+  if (options.workspaces.length === 0) {
+    elements.push(
+      buildMarkdown("<font color='grey'>还没有任何 workspace。在群里执行 `/setup` 创建一个。</font>"),
+    );
+  } else {
+    for (const entry of options.workspaces) {
+      elements.push(_buildWorkspaceRow(entry));
+    }
+  }
+
+  elements.push(_buildDismissButton());
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: "⚙️ 设置面板" },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
+
+/**
+ * Detail card for one workspace: metadata, cloned repos + branches, list of
+ * bound chats, danger button that leads to the delete-confirm card.
+ */
+export interface WorkspaceDetailCardOptions {
+  workspace: Workspace;
+  bindings: GroupWorkspace[];
+  repos: Array<{ name: string; branch: string | null; is_active: boolean }>;
+  is_protected: boolean;
+  /** Live HEAD of the active repo; matches the per-repo row below. */
+  active_branch_head: string | null;
+}
+
+export function buildWorkspaceDetailCard(
+  options: WorkspaceDetailCardOptions,
+): Card {
+  const { workspace, bindings, repos, is_protected, active_branch_head } = options;
+  const activeRepoLine = workspace.active_repo
+    ? `\`${formatRepoRef(workspace.active_repo, active_branch_head ?? "(游离)")}\``
+    : "(未设置)";
+
+  const elements: Element[] = [
+    buildCardIntro({
+      title: `Workspace: ${workspace.name}`,
+      subtitle: workspace.id,
+    }),
+    ...buildSectionBlock({
+      title: "基本信息",
+      lines: [
+        `- 路径：\`${workspace.path}\``,
+        `- 活跃主仓库：${activeRepoLine}`,
+        `- 创建时间：${_formatTs(workspace.created_at)}`,
+        `- 上次活跃：${_formatTs(workspace.last_active_at)} (${_formatRelative(workspace.last_active_at)})`,
+      ],
+    }),
+    ...buildSectionBlock({
+      title: `仓库与分支 (${repos.length})`,
+      lines:
+        repos.length === 0
+          ? ["- (当前 workspace 下还没有任何仓库)"]
+          : repos.map((r) => {
+              const ref = formatRepoRef(r.name, r.branch ?? "(游离)");
+              return `- \`${ref}\`${r.is_active ? "  ← 活跃" : ""}`;
+            }),
+    }),
+    ...buildSectionBlock({
+      title: `绑定的群 (${bindings.length})`,
+      lines:
+        bindings.length === 0
+          ? ["- (没有群绑定到此 workspace)"]
+          : bindings.map((b) => `- \`${b.chat_id}\``),
+    }),
+    _buildDetailActionRow(workspace.id, is_protected),
+  ];
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: `🗂️ ${workspace.name}` },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
+
+/**
+ * Red two-button confirm card shown before anything is actually removed.
+ * The apply button is the only path that triggers cascading deletion.
+ */
+export interface WorkspaceDeleteConfirmCardOptions {
+  workspace: Workspace;
+  binding_count: number;
+  estimated_session_count: number;
+}
+
+export function buildWorkspaceDeleteConfirmCard(
+  options: WorkspaceDeleteConfirmCardOptions,
+): Card {
+  const { workspace, binding_count, estimated_session_count } = options;
+  const elements: Element[] = [
+    buildCardIntro({
+      title: "⚠️  确认删除 Workspace",
+      subtitle: workspace.name,
+    }),
+    buildMarkdown(
+      [
+        "此操作不可撤销，会执行以下清理：",
+        `- 解绑 **${binding_count}** 个群`,
+        `- 级联删除约 **${estimated_session_count}** 个关联 session 及其 task 记录`,
+        `- 移除物理目录 \`${workspace.path}\``,
+        "- 保留 `git-cache/`（其他 workspace 仍可复用）",
+      ].join("\n"),
+    ),
+    _buildDeleteConfirmRow(workspace.id),
+  ];
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: `⚠️ 确认删除 ${workspace.name}` },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
+
+/**
+ * Terminal result card reused by every setting flow (save / delete / error).
+ * Always appends a "返回设置面板" button so the user can re-enter the panel
+ * without having to re-send the slash command. Disable via `show_back: false`
+ * for transient fail states that shouldn't offer re-entry.
+ */
+export function buildSettingResultCard(
+  summary: string,
+  detail: string[] = [],
+  options: { show_back?: boolean } = {},
+): Card {
+  const card = buildResultCard({
+    title: "设置面板",
+    summary,
+    detail,
+  });
+  if (options.show_back ?? true) {
+    const backBtn: ButtonElement = {
+      tag: "button",
+      name: "setting_result_back_btn",
+      text: { tag: "plain_text", content: "返回设置面板" },
+      type: "default",
+      width: "fill",
+      behaviors: [
+        {
+          type: "callback",
+          value: { action: SETTING_ACTION.mainBack },
+        },
+      ],
+    };
+    card.body.elements.push({
+      tag: "column_set",
+      flex_mode: "stretch",
+      horizontal_spacing: "12px",
+      columns: [
+        { tag: "column", width: "weighted", weight: 1, elements: [backBtn] },
+        {
+          tag: "column",
+          width: "weighted",
+          weight: 1,
+          elements: [_buildDismissButton()],
+        },
+      ],
+    });
+  }
+  return card;
+}
+
+function _buildConfigForm(options: SettingMainCardOptions): FormElement {
+  const agentSelect: SelectStaticElement = {
+    tag: "select_static",
+    name: SETTING_FIELD.agentType,
+    placeholder: { tag: "plain_text", content: "选择默认 Agent" },
+    initial_option: options.agent.available_types.includes(
+      options.agent.active_type,
+    )
+      ? options.agent.active_type
+      : options.agent.available_types[0],
+    options: options.agent.available_types.map((t) => ({
+      text: { tag: "plain_text", content: t },
+      value: t,
+    })),
+    width: "fill",
+  };
+
+  const modelInput: InputElement = {
+    tag: "input",
+    name: SETTING_FIELD.agentModel,
+    placeholder: {
+      tag: "plain_text",
+      content: "留空表示让 runner 自选（如 Claude Code 默认）",
+    },
+    default_value: options.config_values.agent_model,
+    width: "fill",
+  };
+
+  const codexChecker: CheckerElement = {
+    tag: "checker",
+    name: SETTING_FIELD.codexIsolateHostEnv,
+    text: {
+      tag: "plain_text",
+      content: "Codex 环境隔离（指向独立 CODEX_HOME）",
+    },
+    checked: options.config_values.codex_isolate_host_env,
+  };
+
+  const retriesInput: InputElement = {
+    tag: "input",
+    name: SETTING_FIELD.maxRetries,
+    placeholder: { tag: "plain_text", content: "正整数，如 3" },
+    default_value: String(options.config_values.max_retries),
+    width: "fill",
+  };
+
+  const submitBtn: ButtonElement = {
+    tag: "button",
+    name: SETTING_ACTION.saveConfig,
+    text: { tag: "plain_text", content: "保存配置" },
+    type: "primary",
+    action_type: "form_submit",
+    width: "fill",
+  };
+
+  // Agent type is the primary choice (wider); Agent Model is rarely tweaked
+  // once set, so it gets a narrower column.
+  const agentRow: ColumnSetElement = {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 2,
+        vertical_spacing: "4px",
+        elements: [
+          buildMarkdown("<font color='grey'>默认 Agent</font>", {
+            text_size: "notation",
+          }),
+          agentSelect,
+        ],
+      },
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 1,
+        vertical_spacing: "4px",
+        elements: [
+          buildMarkdown("<font color='grey'>Agent Model</font>", {
+            text_size: "notation",
+          }),
+          modelInput,
+        ],
+      },
+    ],
+  };
+
+  return {
+    tag: "form",
+    name: "setting_config_form",
+    elements: [
+      buildMarkdown("**全局配置**"),
+      agentRow,
+      buildMarkdown("<font color='grey'>Codex 行为</font>", {
+        text_size: "notation",
+      }),
+      codexChecker,
+      buildMarkdown("<font color='grey'>任务重试上限</font>", {
+        text_size: "notation",
+      }),
+      retriesInput,
+      submitBtn,
+    ],
+  };
+}
+
+function _buildWorkspaceRow(entry: {
+  workspace: Workspace;
+  binding_count: number;
+  is_current: boolean;
+  is_protected: boolean;
+  active_branch_head: string | null;
+}): Element {
+  const { workspace, binding_count, is_current, is_protected, active_branch_head } = entry;
+
+  // Primary line: workspace name in bold. The stable id moves to the meta
+  // line so the title stays short and scannable.
+  const titleEl = buildMarkdown(`**${workspace.name}**`);
+
+  // Secondary line: currently active repo/branch — the single most
+  // operationally relevant fact for each row. Branch comes from the on-disk
+  // HEAD (passed in as `active_branch_head`), matching `/status`: the stored
+  // `active_branch` is only a hint and drifts after the user `checkout`s.
+  const activeEl = buildMarkdown(
+    workspace.active_repo
+      ? `\`${formatRepoRef(workspace.active_repo, active_branch_head ?? "(游离)")}\``
+      : "<font color='grey'>未设置主仓库</font>",
+    { text_size: "notation" },
+  );
+
+  // Meta line: id + last-active badge + (optional) binding count + current
+  // chat tag. The active badge changes color by age so dormant workspaces
+  // are visually obvious without the user having to eyeball timestamps.
+  const activeBadge = _formatActiveBadge(workspace.last_active_at);
+  const metaParts: string[] = [
+    `<font color='grey'>ID \`${workspace.id}\`</font>`,
+    `<font color='${activeBadge.color}'>${activeBadge.text}</font>`,
+  ];
+  if (binding_count > 0) {
+    metaParts.push(`<font color='grey'>${binding_count} 群绑定</font>`);
+  }
+  if (is_current) {
+    metaParts.push("<font color='green'>**当前群**</font>");
+  }
+  const metaEl = buildMarkdown(metaParts.join(" · "), { text_size: "notation" });
+
+  const detailBtn: ButtonElement = {
+    tag: "button",
+    name: `setting_ws_detail_btn_${workspace.id}`,
+    text: { tag: "plain_text", content: "详情" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: {
+          action: SETTING_ACTION.wsDetail,
+          workspace_id: workspace.id,
+        },
+      },
+    ],
+  };
+  const deleteBtn: ButtonElement = {
+    tag: "button",
+    name: `setting_ws_delete_btn_${workspace.id}`,
+    text: { tag: "plain_text", content: "删除" },
+    type: "danger",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: {
+          action: SETTING_ACTION.wsDeletePrompt,
+          workspace_id: workspace.id,
+        },
+      },
+    ],
+  };
+
+  // Buttons sit in a narrow right-hand column; nesting a tight column_set
+  // inside it keeps the two buttons visually adjacent (no big gap) while
+  // still letting the left column stretch to take all remaining width.
+  const buttonStack: ColumnSetElement = {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "4px",
+    columns: is_protected
+      ? [{ tag: "column", width: "weighted", weight: 1, elements: [detailBtn] }]
+      : [
+          { tag: "column", width: "weighted", weight: 1, elements: [detailBtn] },
+          { tag: "column", width: "weighted", weight: 1, elements: [deleteBtn] },
+        ],
+  };
+
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 3,
+        vertical_spacing: "4px",
+        vertical_align: "center",
+        elements: [titleEl, activeEl, metaEl],
+      },
+      {
+        tag: "column",
+        width: is_protected ? "90px" : "170px",
+        vertical_align: "center",
+        elements: [buttonStack],
+      },
+    ],
+  };
+}
+
+function _buildDetailActionRow(
+  workspaceId: string,
+  isProtected: boolean,
+): Element {
+  const backBtn: ButtonElement = {
+    tag: "button",
+    name: "setting_main_back_btn",
+    text: { tag: "plain_text", content: "← 返回" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: { action: SETTING_ACTION.mainBack },
+      },
+    ],
+  };
+  const dismissBtn = _buildDismissButton();
+  if (isProtected) {
+    return {
+      tag: "column_set",
+      flex_mode: "stretch",
+      horizontal_spacing: "12px",
+      columns: [
+        { tag: "column", width: "weighted", weight: 1, elements: [backBtn] },
+        { tag: "column", width: "weighted", weight: 1, elements: [dismissBtn] },
+      ],
+    };
+  }
+  const deleteBtn: ButtonElement = {
+    tag: "button",
+    name: "setting_ws_delete_prompt_btn",
+    text: { tag: "plain_text", content: "删除 Workspace" },
+    type: "danger",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: {
+          action: SETTING_ACTION.wsDeletePrompt,
+          workspace_id: workspaceId,
+        },
+      },
+    ],
+  };
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      { tag: "column", width: "weighted", weight: 1, elements: [backBtn] },
+      { tag: "column", width: "weighted", weight: 1, elements: [dismissBtn] },
+      { tag: "column", width: "weighted", weight: 1, elements: [deleteBtn] },
+    ],
+  };
+}
+
+function _buildDismissButton(): ButtonElement {
+  return {
+    tag: "button",
+    name: "setting_dismiss_btn",
+    text: { tag: "plain_text", content: "关闭" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: { action: SETTING_ACTION.dismiss },
+      },
+    ],
+  };
+}
+
+/**
+ * Dismiss card swapped in when the user clicks "关闭" on any setting card.
+ * Same neutral shape as `buildSettingResultCard` but with no buttons —
+ * leaving the panel cleanly closed.
+ */
+export function buildSettingDismissedCard(): Card {
+  return buildDismissedCard({ title: "设置面板" });
+}
+
+function _buildDeleteConfirmRow(workspaceId: string): Element {
+  const cancelBtn: ButtonElement = {
+    tag: "button",
+    name: "setting_delete_cancel_btn",
+    text: { tag: "plain_text", content: "← 返回" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: { action: SETTING_ACTION.mainBack },
+      },
+    ],
+  };
+  const confirmBtn: ButtonElement = {
+    tag: "button",
+    name: "setting_delete_apply_btn",
+    text: { tag: "plain_text", content: "确认删除" },
+    type: "danger",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: {
+          action: SETTING_ACTION.wsDeleteApply,
+          workspace_id: workspaceId,
+        },
+      },
+    ],
+  };
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      { tag: "column", width: "weighted", weight: 1, elements: [cancelBtn] },
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 1,
+        elements: [_buildDismissButton()],
+      },
+      { tag: "column", width: "weighted", weight: 1, elements: [confirmBtn] },
+    ],
+  };
+}
+
+function _formatTs(ms: number): string {
+  if (!ms) return "(未知)";
+  return dayjs(ms).format("YYYY-MM-DD HH:mm");
+}
+
+function _formatRelative(ms: number): string {
+  if (!ms) return "未知";
+  const diff = Date.now() - ms;
+  if (diff < 60_000) return "刚刚";
+  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)} 分钟前`;
+  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)} 小时前`;
+  if (diff < 30 * 86_400_000) return `${Math.floor(diff / 86_400_000)} 天前`;
+  return dayjs(ms).format("YYYY-MM-DD");
+}
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Color-coded freshness label for a workspace's `last_active_at`.
+ *
+ * - ≤ 3 days → green "活跃 …" — recently used, safe.
+ * - ≤ 30 days → grey "活跃 …" — cold but not abandoned.
+ * - > 30 days → red "超过 N 个月未活跃" — explicit warning to consider pruning.
+ */
+function _formatActiveBadge(ms: number): { text: string; color: string } {
+  if (!ms) return { text: "活跃未知", color: "grey" };
+  const diff = Date.now() - ms;
+  if (diff < 3 * DAY_MS) {
+    return { text: `活跃 ${_formatRelative(ms)}`, color: "green" };
+  }
+  if (diff < 30 * DAY_MS) {
+    return { text: `活跃 ${_formatRelative(ms)}`, color: "grey" };
+  }
+  const months = Math.max(1, Math.floor(diff / (30 * DAY_MS)));
+  return { text: `超过 ${months} 个月未活跃`, color: "red" };
+}
diff --git a/src/kernel/setting/setting-flow.ts b/src/kernel/setting/setting-flow.ts
new file mode 100644
index 0000000..10ee143
--- /dev/null
+++ b/src/kernel/setting/setting-flow.ts
@@ -0,0 +1,593 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { eq, like, or } from "drizzle-orm";
+
+import type { DrizzleDB } from "@/data";
+import {
+  filterUserFacingAgentTypes,
+  getAgentRuntimeState,
+  listRunnerTypes,
+  setRuntimeDefaultAgentType,
+  UnknownAgentTypeError,
+} from "@/kernel/agents";
+import { sessions } from "@/kernel/sessioning/data";
+import {
+  readRepoHead,
+  WorkspaceNotFoundError,
+  WorkspaceProtectedError,
+  type GroupWorkspaceStore,
+  type WorkspaceDeleteResult,
+} from "@/kernel/workspaces";
+import type { GroupWorkspace, Logger, Workspace } from "@/shared";
+import { config, createLogger, type CardActionPayload, type UserMessage } from "@/shared";
+
+import type { FeishuMessageChannel } from "../../community/feishu/messaging/message-channel";
+import type { Card } from "../../community/feishu/messaging/types";
+
+import { writeConfigPatch, type SettingConfigPatch } from "./config-writer";
+import {
+  buildSettingDismissedCard,
+  buildSettingMainCard,
+  buildSettingResultCard,
+  buildWorkspaceDeleteConfirmCard,
+  buildWorkspaceDetailCard,
+  SETTING_ACTION,
+  SETTING_FIELD,
+} from "./setting-card";
+
+/**
+ * Stateful orchestrator for the `/setting` panel.
+ *
+ * Lifecycle:
+ * 1. `start(message)` renders the main panel (global config form + workspace
+ *    list) into the chat and returns.
+ * 2. Every subsequent click routes back through `handleAction(payload)`,
+ *    which replaces the card in place (`updateRawCard`) with a detail view,
+ *    a delete-confirm view, or a terminal result.
+ *
+ * Unlike `/setup`/`/switch`, we intentionally don't track pending cards in
+ * an in-memory map: every action payload carries the `workspace_id` it
+ * applies to, so we can operate statelessly. A stale card from before a
+ * restart still works — the worst case is pointing at a workspace that has
+ * since been deleted, which the flow handles gracefully.
+ */
+export class SettingFlow {
+  private readonly _logger: Logger = createLogger("setting-flow");
+  private readonly _workspaceStore: GroupWorkspaceStore;
+  private readonly _feishuChannels: Map<string, FeishuMessageChannel>;
+  private readonly _db: DrizzleDB;
+
+  constructor(deps: {
+    workspaceStore: GroupWorkspaceStore;
+    feishuChannels: Map<string, FeishuMessageChannel>;
+    db: DrizzleDB;
+  }) {
+    this._workspaceStore = deps.workspaceStore;
+    this._feishuChannels = deps.feishuChannels;
+    this._db = deps.db;
+  }
+
+  /** Entry point for `/setting` and `/workspaces`. */
+  async start(message: UserMessage): Promise<void> {
+    const chatId = message.chat_id;
+    if (!chatId || !message.channel_id) {
+      await this._replyText(message, "❌ /setting 需要飞书会话上下文。");
+      return;
+    }
+    if (!this._isAdmin(message.sender_open_id)) {
+      this._logger.info(
+        { chat_id: chatId, sender_open_id: message.sender_open_id },
+        "rejected /setting from non-admin",
+      );
+      await this._replyText(
+        message,
+        "🚫 你没有 /setting 权限。请联系管理员把你的 open_id 加到 `setting.admin_open_ids`。",
+      );
+      return;
+    }
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) {
+      await this._replyText(message, "❌ 无法找到对应的飞书 channel。");
+      return;
+    }
+    try {
+      const card = this._renderMainCard(chatId);
+      await channel.sendRawCard(chatId, card, {
+        replyTo: message.id,
+        replyInThread: false,
+      });
+    } catch (err) {
+      const detail = _summarizeFeishuError(err);
+      this._logger.error(
+        { err: detail, chat_id: chatId },
+        "failed to render setting card",
+      );
+      const reason = detail.msg
+        ? `${detail.msg}${detail.code ? ` (code ${detail.code})` : ""}`
+        : (err as Error).message;
+      await this._replyText(message, `❌ 渲染设置面板失败：${reason}`);
+    }
+  }
+
+  /** Single entry point for every `setting_*` card action. */
+  async handleAction(payload: CardActionPayload): Promise<void> {
+    const channel = this._feishuChannels.get(payload.channel_id);
+    if (!channel) {
+      this._logger.warn(
+        { channel_id: payload.channel_id, action_name: payload.action_name },
+        "setting action for unknown channel",
+      );
+      return;
+    }
+    if (!this._isAdmin(payload.operator_open_id)) {
+      this._logger.info(
+        {
+          action_name: payload.action_name,
+          operator_open_id: payload.operator_open_id,
+        },
+        "rejected /setting card action from non-admin",
+      );
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSettingResultCard(
+          "🚫 你没有 /setting 权限，无法操作此卡片。",
+          [],
+          { show_back: false },
+        ),
+        "non-admin",
+      );
+      return;
+    }
+    try {
+      switch (payload.action_name) {
+        case SETTING_ACTION.saveConfig:
+          await this._handleSaveConfig(channel, payload);
+          return;
+        case SETTING_ACTION.mainBack:
+          await this._handleMainBack(channel, payload);
+          return;
+        case SETTING_ACTION.wsDetail:
+          await this._handleWsDetail(channel, payload);
+          return;
+        case SETTING_ACTION.wsDeletePrompt:
+          await this._handleWsDeletePrompt(channel, payload);
+          return;
+        case SETTING_ACTION.wsDeleteApply:
+          await this._handleWsDeleteApply(channel, payload);
+          return;
+        case SETTING_ACTION.dismiss:
+          await this._tryUpdateCard(
+            channel,
+            payload.message_id,
+            buildSettingDismissedCard(),
+            "dismiss",
+          );
+          return;
+        default:
+          this._logger.warn(
+            { action_name: payload.action_name },
+            "unknown setting action",
+          );
+      }
+    } catch (err) {
+      this._logger.error(
+        { err, action_name: payload.action_name },
+        "setting action failed",
+      );
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSettingResultCard(`❌ 操作失败：${(err as Error).message}`),
+        "action-error",
+      );
+    }
+  }
+
+  private async _handleSaveConfig(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const raw = payload.form_value;
+    const newAgentType =
+      typeof raw[SETTING_FIELD.agentType] === "string"
+        ? (raw[SETTING_FIELD.agentType] as string).trim()
+        : "";
+    const newAgentModel =
+      typeof raw[SETTING_FIELD.agentModel] === "string"
+        ? (raw[SETTING_FIELD.agentModel] as string).trim()
+        : "";
+    const newCodexIsolate = _coerceBool(raw[SETTING_FIELD.codexIsolateHostEnv]);
+    const parsedRetries = _coerceInt(raw[SETTING_FIELD.maxRetries]);
+
+    if (parsedRetries === null || parsedRetries <= 0) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSettingResultCard(
+          "❌ 任务重试上限必须为正整数，未保存任何改动。",
+        ),
+        "invalid-retries",
+      );
+      return;
+    }
+
+    const patch: SettingConfigPatch = {
+      agents: {
+        default: {
+          type: newAgentType || undefined,
+          model: newAgentModel,
+        },
+        codex: {
+          isolate_host_env: newCodexIsolate,
+        },
+      },
+      tasking: {
+        max_retries: parsedRetries,
+      },
+    };
+
+    const appliedLines: string[] = [];
+    try {
+      writeConfigPatch(patch);
+      appliedLines.push(
+        `- 默认 Agent（配置）：\`${newAgentType || "(未变)"}\``,
+        `- Agent Model：\`${newAgentModel || "(未设置)"}\``,
+        `- Codex 环境隔离：${newCodexIsolate ? "✅ 开启" : "⬜ 关闭"}`,
+        `- 任务重试上限：\`${parsedRetries}\``,
+      );
+    } catch (err) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSettingResultCard(
+          `❌ 写入 config.yaml 失败：${(err as Error).message}`,
+        ),
+        "write-failed",
+      );
+      return;
+    }
+
+    // Keep the runtime override in sync with the configured default when the
+    // user picks a new Agent. Any invalid type throws — we surface it but
+    // still keep the file-level change, since the YAML write already landed.
+    if (newAgentType) {
+      try {
+        const result = setRuntimeDefaultAgentType(newAgentType);
+        appliedLines.push(
+          result.changed
+            ? `- 运行时默认 Agent：\`${result.previousType}\` → \`${result.currentType}\``
+            : `- 运行时默认 Agent：\`${result.currentType}\`（未变）`,
+        );
+      } catch (err) {
+        if (err instanceof UnknownAgentTypeError) {
+          appliedLines.push(
+            `- ⚠️  运行时 Agent 未切换：\`${err.type}\` 不在可用列表 [${err.availableTypes.join(", ")}]`,
+          );
+        } else {
+          throw err;
+        }
+      }
+    }
+
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildSettingResultCard("✅ 配置已保存。", appliedLines),
+      "save-ok",
+    );
+  }
+
+  private async _handleMainBack(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const card = this._renderMainCard(payload.chat_id ?? null);
+    await this._tryUpdateCard(channel, payload.message_id, card, "main-back");
+  }
+
+  private async _handleWsDetail(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const workspaceId = _readWorkspaceId(payload);
+    if (!workspaceId) return;
+    const workspace = this._workspaceStore.getWorkspace(workspaceId);
+    if (!workspace) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSettingResultCard("⚠️  workspace 已不存在，请重新发送 `/setting`。"),
+        "ws-missing",
+      );
+      return;
+    }
+    const bindings = this._workspaceStore
+      .listBindings()
+      .filter((b) => b.workspace_id === workspaceId);
+    const repos = _scanRepos(workspace);
+    const activeBranchHead = workspace.active_repo
+      ? readRepoHead(join(workspace.path, workspace.active_repo)) ?? null
+      : null;
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildWorkspaceDetailCard({
+        workspace,
+        bindings,
+        repos,
+        is_protected: workspace.path === config.paths.default_workspace,
+        active_branch_head: activeBranchHead,
+      }),
+      "ws-detail",
+    );
+  }
+
+  private async _handleWsDeletePrompt(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const workspaceId = _readWorkspaceId(payload);
+    if (!workspaceId) return;
+    const workspace = this._workspaceStore.getWorkspace(workspaceId);
+    if (!workspace) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSettingResultCard("⚠️  workspace 已不存在。"),
+        "ws-missing",
+      );
+      return;
+    }
+    const bindingCount = this._workspaceStore
+      .listBindings()
+      .filter((b) => b.workspace_id === workspaceId).length;
+    const sessionCount = this._countSessionsInWorkspace(workspace.path);
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildWorkspaceDeleteConfirmCard({
+        workspace,
+        binding_count: bindingCount,
+        estimated_session_count: sessionCount,
+      }),
+      "ws-delete-prompt",
+    );
+  }
+
+  private async _handleWsDeleteApply(
+    channel: FeishuMessageChannel,
+    payload: CardActionPayload,
+  ): Promise<void> {
+    const workspaceId = _readWorkspaceId(payload);
+    if (!workspaceId) return;
+    let result: WorkspaceDeleteResult;
+    try {
+      result = this._workspaceStore.deleteWorkspace(workspaceId);
+    } catch (err) {
+      if (err instanceof WorkspaceNotFoundError) {
+        await this._tryUpdateCard(
+          channel,
+          payload.message_id,
+          buildSettingResultCard("⚠️  workspace 已不存在。"),
+          "ws-missing",
+        );
+        return;
+      }
+      if (err instanceof WorkspaceProtectedError) {
+        await this._tryUpdateCard(
+          channel,
+          payload.message_id,
+          buildSettingResultCard("🚫 默认 workspace 受保护，无法删除。"),
+          "ws-protected",
+        );
+        return;
+      }
+      throw err;
+    }
+    const lines = [
+      `- 名称：\`${result.workspace_name}\``,
+      `- ID：\`${result.workspace_id}\``,
+      `- 已解绑 **${result.removed_bindings}** 个群`,
+      `- 已级联删除 **${result.removed_sessions}** 个 session，**${result.removed_tasks}** 条 task 记录`,
+      result.removed_directory
+        ? "- 已删除物理目录"
+        : "- ⚠️  物理目录未能删除（可能已不存在或权限问题），详见日志",
+    ];
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildSettingResultCard(
+        `✅ 已删除 workspace \`${result.workspace_name}\`。`,
+        lines,
+      ),
+      "ws-delete-apply",
+    );
+  }
+
+  private _renderMainCard(currentChatId: string | null): Card {
+    const agentState = getAgentRuntimeState();
+    const availableTypes = filterUserFacingAgentTypes(
+      agentState.availableTypes.length > 0
+        ? agentState.availableTypes
+        : listRunnerTypes(),
+    );
+    const workspaces = this._workspaceStore.listWorkspaces();
+    const bindings = this._workspaceStore.listBindings();
+    const bindingCounts = new Map<string, number>();
+    for (const b of bindings) {
+      bindingCounts.set(
+        b.workspace_id,
+        (bindingCounts.get(b.workspace_id) ?? 0) + 1,
+      );
+    }
+    const currentBinding = currentChatId
+      ? bindings.find((b) => b.chat_id === currentChatId)
+      : undefined;
+    const sortedWorkspaces = [...workspaces].sort(
+      (a, b) => b.last_active_at - a.last_active_at,
+    );
+    return buildSettingMainCard({
+      agent: {
+        active_type: agentState.activeType,
+        available_types: availableTypes,
+      },
+      config_values: {
+        agent_model: config.agents.default.model ?? "",
+        codex_isolate_host_env: config.agents.codex.isolate_host_env,
+        max_retries: config.tasking.max_retries,
+      },
+      workspaces: sortedWorkspaces.map((ws) => ({
+        workspace: ws,
+        binding_count: bindingCounts.get(ws.id) ?? 0,
+        is_current: currentBinding?.workspace_id === ws.id,
+        is_protected: ws.path === config.paths.default_workspace,
+        active_branch_head: ws.active_repo
+          ? readRepoHead(join(ws.path, ws.active_repo)) ?? null
+          : null,
+      })),
+      current_chat_id: currentChatId,
+    });
+  }
+
+  private _countSessionsInWorkspace(workspacePath: string): number {
+    const rows = this._db
+      .select({ id: sessions.id })
+      .from(sessions)
+      .where(
+        or(
+          eq(sessions.cwd, workspacePath),
+          like(sessions.cwd, `${workspacePath}/%`),
+        ),
+      )
+      .all();
+    return rows.length;
+  }
+
+  private async _tryUpdateCard(
+    channel: FeishuMessageChannel,
+    messageId: string,
+    card: Card,
+    stage: string,
+  ): Promise<void> {
+    try {
+      await channel.updateRawCard(messageId, card);
+    } catch (err) {
+      this._logger.error(
+        { err: _summarizeFeishuError(err), stage, message_id: messageId },
+        "setting updateRawCard failed",
+      );
+    }
+  }
+
+  /**
+   * Allowlist gate for `/setting`. Empty `setting.admin_open_ids` means no
+   * restriction (every channel-allowed user may use the panel); otherwise
+   * the sender's open_id must be in the list. Missing `senderOpenId` is
+   * always rejected once a non-empty list is configured.
+   */
+  private _isAdmin(senderOpenId: string | undefined | null): boolean {
+    const adminIds = config.setting.admin_open_ids;
+    if (adminIds.length === 0) return true;
+    return !!senderOpenId && adminIds.includes(senderOpenId);
+  }
+
+  private async _replyText(message: UserMessage, text: string): Promise<void> {
+    if (!message.channel_id) return;
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) return;
+    await channel.replyMessage(
+      message.id,
+      {
+        role: "assistant",
+        session_id: message.session_id,
+        content: [{ type: "text", text }],
+      },
+      { streaming: false, replyInThread: false },
+    );
+  }
+}
+
+function _readWorkspaceId(payload: CardActionPayload): string | null {
+  const wsId = payload.value.workspace_id;
+  return typeof wsId === "string" && wsId ? wsId : null;
+}
+
+function _coerceBool(v: unknown): boolean {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "string") {
+    const lower = v.toLowerCase();
+    return lower === "true" || lower === "1" || lower === "on";
+  }
+  return false;
+}
+
+function _coerceInt(v: unknown): number | null {
+  if (typeof v === "number" && Number.isFinite(v)) return Math.trunc(v);
+  if (typeof v === "string") {
+    const parsed = parseInt(v.trim(), 10);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+interface RepoSummary {
+  name: string;
+  branch: string | null;
+  is_active: boolean;
+}
+
+function _scanRepos(workspace: Workspace): RepoSummary[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(workspace.path, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .filter((name) => !name.startsWith("."));
+  } catch {
+    return [];
+  }
+  const repos: RepoSummary[] = [];
+  for (const name of entries) {
+    const repoPath = join(workspace.path, name);
+    if (!existsSync(join(repoPath, ".git"))) continue;
+    const head = readRepoHead(repoPath);
+    repos.push({
+      name,
+      branch: head ?? null,
+      is_active: name === workspace.active_repo,
+    });
+  }
+  return repos.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// Expose GroupWorkspace so `_handleWsDetail` callers don't need to import from
+// deep paths — not used today but keeps the barrel clean if we ever surface
+// binding details publicly.
+export type { GroupWorkspace };
+
+/**
+ * Extract the code/msg/status trio from a Feishu/axios error so logs and
+ * user-facing messages carry the actual server reason instead of the generic
+ * "Request failed with status code 400".
+ */
+function _summarizeFeishuError(err: unknown): {
+  code?: number;
+  msg?: string;
+  status?: number;
+} {
+  if (!err || typeof err !== "object") return {};
+  const candidate = err as {
+    response?: {
+      status?: number;
+      data?: { code?: number; msg?: string };
+    };
+    message?: string;
+  };
+  return {
+    code: candidate.response?.data?.code,
+    msg: candidate.response?.data?.msg ?? candidate.message,
+    status: candidate.response?.status,
+  };
+}
diff --git a/src/kernel/setup/card-ui.ts b/src/kernel/setup/card-ui.ts
new file mode 100644
index 0000000..3532d85
--- /dev/null
+++ b/src/kernel/setup/card-ui.ts
@@ -0,0 +1,234 @@
+import type {
+  Card,
+  Color,
+  CollapsiblePanel,
+  Element,
+  MarkdownElement,
+} from "../../community/feishu/messaging/types";
+
+type CardTone = "info" | "success" | "warning" | "danger" | "neutral";
+
+const CARD_TONE_STYLES: Record<
+  CardTone,
+  {
+    border: Color;
+    background: Color;
+  }
+> = {
+  info: {
+    border: "wathet-200",
+    background: "wathet-50",
+  },
+  success: {
+    border: "green-200",
+    background: "green-50",
+  },
+  warning: {
+    border: "orange-200",
+    background: "orange-50",
+  },
+  danger: {
+    border: "red-200",
+    background: "red-50",
+  },
+  neutral: {
+    border: "grey-300",
+    background: "grey-50",
+  },
+};
+
+export function buildCardIntro(options: {
+  title: string;
+  subtitle?: string;
+}): MarkdownElement {
+  return buildMarkdown(
+    options.subtitle
+      ? [`**${options.title}**`, "", `<font color='grey'>${options.subtitle}</font>`].join("\n")
+      : `**${options.title}**`,
+  );
+}
+
+export function buildMarkdown(
+  content: string,
+  extra: Partial<Omit<MarkdownElement, "tag" | "content">> = {},
+): MarkdownElement {
+  return {
+    tag: "markdown",
+    content: optimizeCardMarkdown(content),
+    ...extra,
+  };
+}
+
+export function buildSectionPanel(options: {
+  title: string;
+  elements: Element[];
+  expanded?: boolean;
+  tone?: CardTone;
+}): CollapsiblePanel {
+  const tone = options.tone ?? "neutral";
+  return {
+    tag: "collapsible_panel",
+    expanded: options.expanded ?? false,
+    background_color: CARD_TONE_STYLES[tone].background,
+    border: {
+      color: CARD_TONE_STYLES[tone].border,
+      corner_radius: "8px",
+    },
+    padding: "0px",
+    vertical_spacing: "8px",
+    header: {
+      title: {
+        tag: "plain_text",
+        content: options.title,
+        text_size: "medium",
+      },
+      icon: {
+        tag: "standard_icon",
+        token: "right_outlined",
+        color: "grey",
+      },
+      icon_position: "right",
+      icon_expanded_angle: 90,
+      padding: "10px 12px 10px 12px",
+      width: "fill",
+    },
+    elements: options.elements,
+  };
+}
+
+export function buildSectionBlock(options: {
+  title: string;
+  lines: string[];
+}): Element[] {
+  return [
+    buildMarkdown(`**${options.title}**`),
+    buildMarkdown(options.lines.join("\n")),
+  ];
+}
+
+/**
+ * Card emitted when a user explicitly dismisses an interactive flow without
+ * completing it. Title + subtitle only — no body line and no buttons. We
+ * deliberately avoid `buildResultCard` here because it renders the summary
+ * twice (once in the subtitle slot, once in the body), which read as
+ * duplicated copy on small dismiss messages like "已关闭".
+ */
+export function buildDismissedCard(options: {
+  title: string;
+  summary?: string;
+}): Card {
+  const summary = options.summary ?? "已关闭，可重新发送原命令打开新卡片。";
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: summarizeForSubtitle(summary) },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements: [
+        buildCardIntro({
+          title: options.title,
+          subtitle: summary,
+        }),
+      ],
+    },
+  };
+}
+
+export function buildResultCard(options: {
+  title: string;
+  summary: string;
+  detail?: string[];
+}): Card {
+  const tone = inferToneFromSummary(options.summary);
+  const elements: Element[] = [
+    buildCardIntro({
+      title: options.title,
+      subtitle: summarizeForSubtitle(options.summary),
+    }),
+    buildMarkdown(options.summary),
+  ];
+
+  if ((options.detail?.length ?? 0) > 0) {
+    if (tone !== "neutral") {
+      elements.push(
+        buildMarkdown(`<font color='grey'>详情</font>`, {
+          text_size: "notation",
+        }),
+      );
+    }
+    elements.push(buildMarkdown(options.detail!.join("\n")));
+  }
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: {
+        content: summarizeForSubtitle(options.summary),
+      },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements,
+    },
+  };
+}
+
+export function inferToneFromSummary(summary: string): CardTone {
+  if (summary.startsWith("✅")) return "success";
+  if (summary.startsWith("⏳")) return "info";
+  if (summary.startsWith("⚠️") || summary.startsWith("🚫")) return "warning";
+  if (summary.startsWith("❌")) return "danger";
+  return "neutral";
+}
+
+function summarizeForSubtitle(summary: string): string {
+  // Feishu doesn't re-parse `<at>` tags inside `<font>` wrappers, which is
+  // what `buildCardIntro` uses for subtitles — leaving the tag in would
+  // dump its raw `at id=...` attribute text into the card. Strip mentions
+  // here so the subtitle stays plain. Also collapse the resulting double
+  // spaces so it reads cleanly.
+  return summary
+    .replace(/<at\b[^>]*>\s*<\/at>/g, "")
+    .replace(/^[^\p{L}\p{N}`]+/u, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 80);
+}
+
+/**
+ * Lightweight markdown normalization borrowed from the richer Feishu card
+ * pipeline in `happyclaw`, trimmed to what these setup cards need.
+ */
+export function optimizeCardMarkdown(text: string): string {
+  if (!text.trim()) return text;
+  const mark = "__CARD_CODE_BLOCK__";
+  const codeBlocks: string[] = [];
+
+  let normalized = text.replace(/```[\s\S]*?```/g, (block) => {
+    const idx = codeBlocks.push(block) - 1;
+    return `${mark}${idx}__`;
+  });
+
+  if (/^#{1,3} /m.test(normalized)) {
+    normalized = normalized.replace(/^#{2,6} (.+)$/gm, "##### $1");
+    normalized = normalized.replace(/^# (.+)$/gm, "#### $1");
+  }
+
+  normalized = normalized.replace(/^([^|\n].*)\n(\|.+\|)/gm, "$1\n\n$2");
+  normalized = normalized.replace(/\n{3,}/g, "\n\n");
+
+  codeBlocks.forEach((block, idx) => {
+    normalized = normalized.replace(`${mark}${idx}__`, `\n<br>\n${block}\n<br>\n`);
+  });
+
+  return normalized.trim();
+}
diff --git a/src/kernel/setup/setup-card.ts b/src/kernel/setup/setup-card.ts
new file mode 100644
index 0000000..da00cd6
--- /dev/null
+++ b/src/kernel/setup/setup-card.ts
@@ -0,0 +1,317 @@
+import type { PredefinedRepo } from "@/shared";
+
+import type {
+  ButtonElement,
+  Card,
+  CheckerElement,
+  ColumnSetElement,
+  Element,
+  FormElement,
+  InputElement,
+  SelectStaticElement,
+} from "../../community/feishu/messaging/types";
+
+import {
+  buildCardIntro,
+  buildDismissedCard,
+  buildMarkdown,
+  buildResultCard,
+  buildSectionBlock,
+} from "./card-ui";
+
+/**
+ * Action discriminator for the "关闭" callback button on the setup card.
+ * Lives next to `setup_submit` (form_submit) so the kernel can route both
+ * back to `SetupFlow`.
+ */
+export const SETUP_DISMISS_ACTION = "setup_dismiss";
+
+/**
+ * Field naming convention used by both the card renderer and the submit
+ * handler. Keep them in one place so the two sides cannot drift apart.
+ */
+export const SETUP_FIELD = {
+  workspaceName: "workspace_name",
+  repoChecker: (name: string) => `repo_${name}`,
+  branchInput: (name: string) => `branch_${name}`,
+  primaryRepo: "primary_repo",
+} as const;
+
+/**
+ * Per-repo pre-fill state for re-runs of `/setup`. When a repo is already
+ * cloned in the workspace we surface it on the card as `checked: true` +
+ * `disabled: true` so the user cannot uncheck it, and pre-fill the branch
+ * input with the repo's current HEAD so editing = branch switch on submit.
+ */
+export interface RepoPrefill {
+  /** Repo is already cloned → checker is forced on and disabled. */
+  already_cloned: boolean;
+  /** Branch to pre-fill in the input (current HEAD for existing repos). */
+  current_branch?: string;
+}
+
+export interface SetupCardOptions {
+  /** Keyed by repo name. Missing entries render as unchecked + editable. */
+  prefills?: Record<string, RepoPrefill>;
+  /** Primary repo to preselect in the bottom dropdown (usually current active_repo). */
+  primary_repo?: string;
+  /**
+   * Pre-fill + lock state for the workspace-name input.
+   * - First run: `value` is the suggested default (editable); no `id` yet.
+   * - Re-run: `value` is the current workspace directory name, `locked: true`,
+   *   `id` is the stable workspace id shown alongside so the user can copy
+   *   it out and `/bind <id>` from another group.
+   */
+  workspace_name?: { value: string; locked: boolean; id?: string };
+}
+
+/**
+ * Build the interactive `/setup` card.
+ *
+ * Compared with the original plain-markdown card, this version adds:
+ * - a proper card head so the action is recognizable in chat history
+ * - a collapsible "how it works" section
+ * - a current-state summary when editing an existing workspace
+ * - clearer per-repo rows (name/description/status separated from branch input)
+ */
+export function buildSetupCard(
+  catalog: PredefinedRepo[],
+  options: SetupCardOptions = {},
+): Card {
+  const prefills = options.prefills ?? {};
+  const hasExisting = Object.values(prefills).some((p) => p.already_cloned);
+  const lockedRepos = catalog
+    .filter((repo) => prefills[repo.name]?.already_cloned)
+    .map((repo) => repo.name);
+
+  const formElements: Element[] = [];
+
+  if (options.workspace_name) {
+    formElements.push(..._buildWorkspaceNameInput(options.workspace_name));
+  }
+
+  formElements.push(
+    buildMarkdown("**仓库与分支**"),
+  );
+
+  for (const repo of catalog) {
+    formElements.push(_buildRepoRow(repo, prefills[repo.name]));
+  }
+
+  formElements.push(
+    buildMarkdown("**主仓库**"),
+  );
+  formElements.push(_buildPrimarySelect(catalog, options.primary_repo));
+  formElements.push(_buildSubmitButton(hasExisting));
+
+  const form: FormElement = {
+    tag: "form",
+    name: "setup_form",
+    elements: formElements,
+  };
+
+  const dismissBtn = _buildDismissButton();
+
+  const bodyElements: Element[] = [
+    buildCardIntro({
+      title: hasExisting ? "更新 Workspace" : "初始化 Workspace",
+    }),
+  ];
+
+  if (hasExisting) {
+    const currentSummaryLines = [
+      `- 已纳管仓库：${lockedRepos.map((name) => `\`${name}\``).join("、") || "（暂无）"}`,
+      `- 当前主仓库：\`${options.primary_repo ?? "（未设置）"}\``,
+    ];
+    if (options.workspace_name?.id) {
+      currentSummaryLines.push(`- Workspace ID：\`${options.workspace_name.id}\``);
+    }
+    bodyElements.push(...buildSectionBlock({
+      title: "当前状态",
+      lines: currentSummaryLines,
+    }));
+  }
+
+  bodyElements.push(form);
+  bodyElements.push(dismissBtn);
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: {
+        content: hasExisting ? "📦 更新 workspace" : "📦 初始化 workspace",
+      },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements: bodyElements,
+    },
+  };
+}
+
+function _buildDismissButton(): ButtonElement {
+  return {
+    tag: "button",
+    name: "setup_dismiss_btn",
+    text: { tag: "plain_text", content: "关闭" },
+    type: "default",
+    width: "fill",
+    behaviors: [
+      {
+        type: "callback",
+        value: { action: SETUP_DISMISS_ACTION },
+      },
+    ],
+  };
+}
+
+function _buildWorkspaceNameInput(
+  state: NonNullable<SetupCardOptions["workspace_name"]>,
+): Element[] {
+  const input: InputElement = {
+    tag: "input",
+    name: SETUP_FIELD.workspaceName,
+    placeholder: { tag: "plain_text", content: "workspace 名称" },
+    default_value: state.value,
+    width: "fill",
+  };
+
+  const elements: Element[] = [
+    buildMarkdown("**Workspace 名称**"),
+    input,
+  ];
+
+  if (state.id) {
+    elements.push(
+      buildMarkdown(`<font color='grey'>当前 Workspace ID：\`${state.id}\`</font>`, {
+        text_size: "notation",
+      }),
+    );
+  }
+
+  return elements;
+}
+
+function _buildRepoRow(
+  repo: PredefinedRepo,
+  prefill?: RepoPrefill,
+): ColumnSetElement {
+  const alreadyCloned = prefill?.already_cloned === true;
+  const checker: CheckerElement = {
+    tag: "checker",
+    name: SETUP_FIELD.repoChecker(repo.name),
+    text: { tag: "plain_text", content: repo.name },
+    checked: alreadyCloned,
+    disabled: alreadyCloned,
+  };
+  const branchInput: InputElement = {
+    tag: "input",
+    name: SETUP_FIELD.branchInput(repo.name),
+    placeholder: { tag: "plain_text", content: "master" },
+    default_value: prefill?.current_branch,
+    width: "fill",
+  };
+
+  return {
+    tag: "column_set",
+    flex_mode: "stretch",
+    horizontal_spacing: "12px",
+    columns: [
+      {
+        tag: "column",
+        width: "weighted",
+        weight: 1,
+        elements: [
+          checker,
+          ...(repo.description
+            ? [
+                buildMarkdown(
+                  `<font color='grey'>${repo.description}</font>`,
+                  { text_size: "notation" },
+                ),
+              ]
+            : []),
+          ...(alreadyCloned
+            ? [
+                buildMarkdown(
+                  "<font color='green'>已存在于当前 workspace，可直接修改分支。</font>",
+                  { text_size: "notation" },
+                ),
+              ]
+            : []),
+        ],
+      },
+      {
+        tag: "column",
+        width: "160px",
+        elements: [
+          buildMarkdown("<font color='grey'>分支</font>", { text_size: "notation" }),
+          branchInput,
+        ],
+      },
+    ],
+  };
+}
+
+function _buildPrimarySelect(
+  catalog: PredefinedRepo[],
+  preselected?: string,
+): SelectStaticElement {
+  const initial =
+    preselected && catalog.some((r) => r.name === preselected)
+      ? preselected
+      : catalog[0]?.name;
+  return {
+    tag: "select_static",
+    name: SETUP_FIELD.primaryRepo,
+    placeholder: { tag: "plain_text", content: "选择主仓库（默认第一个）" },
+    initial_option: initial,
+    options: catalog.map((r) => ({
+      text: { tag: "plain_text", content: r.name },
+      value: r.name,
+    })),
+    width: "fill",
+  };
+}
+
+function _buildSubmitButton(hasExisting: boolean): ButtonElement {
+  return {
+    tag: "button",
+    name: "setup_submit",
+    text: {
+      tag: "plain_text",
+      content: hasExisting ? "保存并更新" : "开始初始化",
+    },
+    type: "primary",
+    action_type: "form_submit",
+    width: "fill",
+  };
+}
+
+/**
+ * Result card rendered after the submit handler finishes. Replaces the
+ * original card in place via `updateRawCard`.
+ */
+export function buildSetupResultCard(
+  summary: string,
+  perRepoLines: string[],
+): Card {
+  return buildResultCard({
+    title: "Workspace 处理结果",
+    summary,
+    detail: perRepoLines,
+  });
+}
+
+/**
+ * Dismiss card shown when the user clicks "关闭" on a setup card without
+ * submitting. Replaces the original card in place so the form elements
+ * are no longer interactable.
+ */
+export function buildSetupDismissedCard(): Card {
+  return buildDismissedCard({ title: "Workspace 初始化" });
+}
diff --git a/src/kernel/setup/setup-flow.ts b/src/kernel/setup/setup-flow.ts
new file mode 100644
index 0000000..f7f9d12
--- /dev/null
+++ b/src/kernel/setup/setup-flow.ts
@@ -0,0 +1,676 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { formatRepoRef } from "@/kernel/repo-ref";
+import type { Logger } from "@/shared";
+import {
+  createLogger,
+  loadPredefinedRepos,
+  slugifyWorkspaceName,
+  type CardActionPayload,
+  type GroupWorkspace,
+  type PredefinedRepo,
+  type UserMessage,
+} from "@/shared";
+
+import type { FeishuMessageChannel } from "../../community/feishu/messaging/message-channel";
+import type { Card } from "../../community/feishu/messaging/types";
+import { ensureCachedMirror, type GroupWorkspaceStore } from "../workspaces";
+
+import {
+  buildSetupCard,
+  buildSetupDismissedCard,
+  buildSetupResultCard,
+  SETUP_FIELD,
+  type RepoPrefill,
+} from "./setup-card";
+
+/**
+ * In-memory pending state for a `/setup` card that has been sent but not
+ * yet submitted. Dropped on kernel restart — expired cards surface a clear
+ * error back to the user instead of being silently honored.
+ */
+interface PendingSetup {
+  chat_id: string;
+  initiator_open_id: string;
+  catalog_snapshot: PredefinedRepo[];
+  /**
+   * Repo names that were already cloned when the card was rendered.
+   * Their checkers are disabled on the card, so form submissions may not
+   * echo their checked state back — we force-include them on submit.
+   */
+  locked_repos: Set<string>;
+  /** Existing workspace id, when editing an already-bound workspace. */
+  locked_workspace_id?: string;
+  created_at: number;
+}
+
+interface RepoResult {
+  name: string;
+  /** The branch the user requested in the form. */
+  branch: string;
+  /**
+   * The branch the repo is actually on after clone+checkout. Equal to `branch`
+   * on success; on `checkout_failed` it falls back to whatever the clone
+   * landed on (the repo's default branch). Unset only on `clone_failed`.
+   */
+  actual_branch?: string;
+  status: "cloned" | "exists" | "clone_failed" | "checkout_failed";
+  detail?: string;
+}
+
+/**
+ * Stateful orchestrator for the `/setup` interactive flow.
+ *
+ * Lifecycle per invocation:
+ * 1. `start(message)` loads the catalog from `REPOS.md`, renders the card,
+ *    and remembers the catalog snapshot keyed by the outbound message id.
+ * 2. The kernel routes a `card:action` with `action_name === "setup_submit"`
+ *    to `handleSubmit(payload)`.
+ * 3. The handler clones the selected repos, checks out the requested branches,
+ *    upserts the group binding, and replaces the original card with a result
+ *    card via `updateRawCard`.
+ *
+ * Single-writer: all pending-state access stays on this instance. One pending
+ * setup per chat is implicit — issuing `/setup` again replaces the key.
+ */
+export class SetupFlow {
+  private readonly _logger: Logger = createLogger("setup-flow");
+  private readonly _workspaceStore: GroupWorkspaceStore;
+  private readonly _feishuChannels: Map<string, FeishuMessageChannel>;
+  private readonly _pending = new Map<string, PendingSetup>();
+
+  constructor(deps: {
+    workspaceStore: GroupWorkspaceStore;
+    feishuChannels: Map<string, FeishuMessageChannel>;
+  }) {
+    this._workspaceStore = deps.workspaceStore;
+    this._feishuChannels = deps.feishuChannels;
+  }
+
+  /**
+   * Entry point invoked from `kernel._handleInboundMessage` when the inbound
+   * text is `/setup`. Re-runnable: on a second invocation the card renders
+   * already-cloned repos as locked checkers with their current branches
+   * pre-filled, so the user can add new repos or switch branches without
+   * being able to accidentally drop existing ones.
+   */
+  async start(message: UserMessage): Promise<void> {
+    const chatId = message.chat_id;
+    if (!chatId || !message.channel_id) {
+      await this._replyText(message, "❌ /setup 仅在飞书群内可用。");
+      return;
+    }
+    // P2P is intentionally kept reuse-only — creating workspaces from single
+    // chats would produce stray rows keyed to every user's P2P chat_id and
+    // make the workspace list hard to reason about. Point users at /switch
+    // instead, which lets them bind to any already-existing workspace.
+    if (message.chat_type === "single") {
+      await this._replyText(
+        message,
+        "❌ /setup 仅在飞书群内可用；单聊请使用 `/switch` 挑选一个已有 workspace。",
+      );
+      return;
+    }
+    const catalog = loadPredefinedRepos();
+    if (catalog.length === 0) {
+      await this._replyText(
+        message,
+        "❌ 仓库目录为空，请在 `$AGENTARA_HOME/REPOS.md` 里添加仓库条目（参考文件顶部的示例）。",
+      );
+      return;
+    }
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) {
+      await this._replyText(message, "❌ 无法找到对应的飞书 channel。");
+      return;
+    }
+
+    // Re-runs reuse the existing workspace path (locked on the card);
+    // first runs propose a slug derived from the group name and let the
+    // user customize it. We defer creating the binding/dir until submit.
+    const binding = this._workspaceStore.getBinding(chatId);
+    const workspaceNameState = await this._resolveWorkspaceNameState(
+      chatId,
+      binding,
+      channel,
+    );
+    const { prefills, lockedRepos } = binding
+      ? this._buildPrefills(binding.workspace_path, catalog)
+      : { prefills: {}, lockedRepos: new Set<string>() };
+
+    const card = buildSetupCard(catalog, {
+      prefills,
+      primary_repo: binding?.active_repo ?? undefined,
+      workspace_name: workspaceNameState,
+    });
+    const cardMessageId = await channel.sendRawCard(chatId, card, {
+      replyTo: message.id,
+    });
+    this._pending.set(cardMessageId, {
+      chat_id: chatId,
+      initiator_open_id: message.sender_open_id ?? "",
+      catalog_snapshot: catalog,
+      locked_repos: lockedRepos,
+      locked_workspace_id: binding?.workspace_id,
+      created_at: Date.now(),
+    });
+    this._logger.info(
+      { chat_id: chatId, card_message_id: cardMessageId },
+      "setup card sent",
+    );
+  }
+
+  /**
+   * Entry point invoked from the kernel's `card:action` listener when the
+   * payload's `action_name === "setup_submit"`. Looks up the pending state
+   * by `payload.message_id` and either rejects the submission (expired,
+   * wrong user, invalid selection) or runs the clone+bind sequence.
+   */
+  async handleSubmit(payload: CardActionPayload): Promise<void> {
+    const channel = this._feishuChannels.get(payload.channel_id);
+    if (!channel) {
+      this._logger.warn(
+        { channel_id: payload.channel_id },
+        "received card action for unknown channel",
+      );
+      return;
+    }
+    const pending = this._pending.get(payload.message_id);
+    if (!pending) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSetupResultCard(
+          "⚠️  这张卡片已失效，请重新发送 `/setup`。",
+          [],
+        ),
+        "expired",
+      );
+      return;
+    }
+    if (
+      pending.initiator_open_id &&
+      payload.operator_open_id !== pending.initiator_open_id
+    ) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSetupResultCard("🚫 这不是你的表单。", []),
+        "non-initiator",
+      );
+      return;
+    }
+
+    this._pending.delete(payload.message_id);
+
+    const selections = this._parseFormValue(
+      payload.form_value,
+      pending.catalog_snapshot,
+      pending.locked_repos,
+    );
+
+    const rawPrimary =
+      typeof payload.form_value[SETUP_FIELD.primaryRepo] === "string"
+        ? (payload.form_value[SETUP_FIELD.primaryRepo] as string)
+        : "";
+    // Zero-repo submit is allowed: the user just wants to create or rename
+    // the workspace. We skip the clone loop and only touch the binding row.
+    const firstSel = selections[0];
+    const primary = firstSel
+      ? (selections.find((s) => s.name === rawPrimary)?.name ?? firstSel.name)
+      : null;
+
+    // Swap the card to a "working" state immediately so the user sees that
+    // the submit landed, then run clones (possibly long) before the final
+    // update. If this patch fails, we still proceed to the clone work.
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      selections.length > 0
+        ? buildSetupResultCard(
+            `⏳ 正在初始化 \`${selections.map((s) => s.name).join("、")}\`…`,
+            selections.map(
+              (s) => `- \`${formatRepoRef(s.name, s.branch)}\``,
+            ),
+          )
+        : buildSetupResultCard("⏳ 正在更新 workspace…", []),
+      "pending-state",
+    );
+
+    // Workspace name is a pure display label — freely editable on every
+    // run. The directory path is derived from the stable workspace id by
+    // the store, so changing the name never moves files on disk. We resolve
+    // the requested name here and pass it through; the store's mutation
+    // path decides whether to create a new workspace or rename an existing
+    // one. The old `workspace_path` hint is no longer useful.
+    const workspaceName = this._resolveWorkspaceNameFromForm(
+      payload.form_value[SETUP_FIELD.workspaceName],
+      pending.chat_id,
+    );
+
+    const results: RepoResult[] = [];
+    const provisionalBinding = this._workspaceStore.upsertBinding(
+      pending.chat_id,
+      {
+        workspace_id: pending.locked_workspace_id,
+        workspace_name: workspaceName,
+      },
+    );
+    const workspacePath = provisionalBinding.workspace_path;
+    for (const sel of selections) {
+      results.push(await this._cloneAndCheckout(workspacePath, sel));
+    }
+
+    // Skip the active-repo update when the user didn't select anything — we
+    // don't want to clobber an existing active_repo just because they popped
+    // /setup open to rename the workspace.
+    let binding = provisionalBinding;
+    let activeRepo: string | null = provisionalBinding.active_repo ?? null;
+    let activeBranch: string | null = provisionalBinding.active_branch ?? null;
+    if (primary) {
+      const primaryResult = results.find((r) => r.name === primary);
+      // active_branch comes from `actual_branch`, which is always set unless
+      // the clone itself failed. If the requested branch didn't exist, we
+      // bind to whatever the clone landed on (usually the remote HEAD)
+      // instead of null.
+      activeRepo =
+        primaryResult && primaryResult.status !== "clone_failed"
+          ? primary
+          : null;
+      activeBranch = primaryResult?.actual_branch ?? null;
+      binding = this._workspaceStore.upsertBinding(pending.chat_id, {
+        active_repo: activeRepo,
+        active_branch: activeBranch,
+      });
+    }
+
+    const lines = [
+      `- Workspace ID: \`${binding.workspace_id}\``,
+      `- Workspace 名称: \`${binding.workspace_name}\``,
+      ...results.map(_formatResultLine),
+    ];
+    const summary = selections.length === 0
+      ? pending.locked_workspace_id
+        ? `✅ Workspace 名称已更新为 \`${binding.workspace_name}\`（未克隆新仓库）。`
+        : `✅ Workspace \`${binding.workspace_name}\` 已创建（暂未克隆仓库；可后续 \`/clone\` 或重发 \`/setup\`）。`
+      : activeRepo && activeBranch
+        ? `✅ 初始化完成，主仓库 \`${formatRepoRef(activeRepo, activeBranch)}\`。`
+        : "⚠️  workspace 已创建，但这次没有成功设置主仓库。";
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildSetupResultCard(summary, lines),
+      "final-result",
+    );
+    this._logger.info(
+      {
+        chat_id: pending.chat_id,
+        primary,
+        results: results.map((r) => ({ name: r.name, status: r.status })),
+      },
+      "setup submit completed",
+    );
+  }
+
+  /**
+   * Entry point for the "关闭" callback button on an open setup card. Clears
+   * any pending state for that message and swaps the card for a no-button
+   * dismissed state so the form elements are no longer interactable.
+   */
+  async handleDismiss(payload: CardActionPayload): Promise<void> {
+    const channel = this._feishuChannels.get(payload.channel_id);
+    if (!channel) {
+      this._logger.warn(
+        { channel_id: payload.channel_id },
+        "received setup dismiss for unknown channel",
+      );
+      return;
+    }
+    const pending = this._pending.get(payload.message_id);
+    if (pending && pending.initiator_open_id &&
+      payload.operator_open_id !== pending.initiator_open_id) {
+      // Don't let a non-initiator close someone else's card; surface the
+      // same wrong-user copy as submit.
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSetupResultCard("🚫 这不是你的表单。", []),
+        "dismiss-non-initiator",
+      );
+      return;
+    }
+    this._pending.delete(payload.message_id);
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildSetupDismissedCard(),
+      "dismiss",
+    );
+    this._logger.info(
+      { chat_id: pending?.chat_id, message_id: payload.message_id },
+      "setup card dismissed",
+    );
+  }
+
+  /**
+   * `updateRawCard` wrapper that logs the Feishu error body instead of
+   * crashing the handleSubmit flow. On failure we press on — the user at
+   * least knows clone ran from logs, even if the UI card is stuck.
+   */
+  private async _tryUpdateCard(
+    channel: FeishuMessageChannel,
+    messageId: string,
+    card: Card,
+    stage: string,
+  ): Promise<void> {
+    try {
+      await channel.updateRawCard(messageId, card);
+    } catch (err) {
+      const detail = _summarizeFeishuError(err);
+      this._logger.error(
+        { err: detail, stage, message_id: messageId },
+        "updateRawCard failed",
+      );
+    }
+  }
+
+  private _parseFormValue(
+    formValue: Record<string, unknown>,
+    catalog: PredefinedRepo[],
+    lockedRepos: Set<string>,
+  ): Array<{ repo: PredefinedRepo; name: string; branch: string }> {
+    const out: Array<{ repo: PredefinedRepo; name: string; branch: string }> =
+      [];
+    for (const repo of catalog) {
+      const rawChecked = formValue[SETUP_FIELD.repoChecker(repo.name)];
+      // Locked repos are rendered with disabled checkers — some Feishu
+      // clients don't echo disabled values back, so force-include them.
+      const isSelected =
+        lockedRepos.has(repo.name) || _isTruthyChecker(rawChecked);
+      if (!isSelected) continue;
+      const rawBranch = formValue[SETUP_FIELD.branchInput(repo.name)];
+      const branch =
+        typeof rawBranch === "string" && rawBranch.trim()
+          ? rawBranch.trim()
+          : "master";
+      out.push({ repo, name: repo.name, branch });
+    }
+    return out;
+  }
+
+  /**
+   * Build the workspace-name input's pre-fill + lock state.
+   *
+   * - Re-run (binding exists): the current directory basename is locked in
+   *   and the stable workspace id is surfaced too, so the user can copy it
+   *   out and run `/bind <id>` from another group.
+   * - First run: try to fetch the Feishu group name; slugify it and append
+   *   `-workspace` to produce a human-readable default. If the group name
+   *   is unavailable or sluggifies to nothing, fall back to a chat-id
+   *   prefix so the input never starts empty.
+   */
+  private async _resolveWorkspaceNameState(
+    chatId: string,
+    binding: GroupWorkspace | null,
+    channel: FeishuMessageChannel,
+  ): Promise<{ value: string; locked: boolean; id?: string }> {
+    if (binding) {
+      return {
+        value: binding.workspace_name,
+        locked: true,
+        id: binding.workspace_id,
+      };
+    }
+    const groupName = await channel.getChatName(chatId);
+    const slug = groupName ? slugifyWorkspaceName(groupName) : "";
+    const fallback = _chatIdFallbackSlug(chatId);
+    const value = slug ? `${slug}-workspace` : `${fallback}-workspace`;
+    return { value, locked: false };
+  }
+
+  /**
+   * Resolve the workspace path from the form's `workspace_name` field on
+   * first-run submission. Sluggifies whatever the user typed; if nothing
+   * usable survives (empty/whitespace-only input), falls back to the
+   * chat-id-based path so we never write a binding with an empty name.
+   */
+  private _resolveWorkspaceNameFromForm(
+    rawValue: unknown,
+    chatId: string,
+  ): string {
+    const slug =
+      typeof rawValue === "string" ? slugifyWorkspaceName(rawValue) : "";
+    if (slug) return slug;
+    return _chatIdFallbackSlug(chatId);
+  }
+
+  /**
+   * Compute per-repo pre-fill state for the card: which catalog repos are
+   * already cloned in this workspace and what branch each is currently on.
+   * The set of locked repo names is tracked so the submit handler can
+   * force-include them even if the card's disabled checker swallows the
+   * checked state.
+   */
+  private _buildPrefills(
+    workspacePath: string,
+    catalog: PredefinedRepo[],
+  ): { prefills: Record<string, RepoPrefill>; lockedRepos: Set<string> } {
+    const prefills: Record<string, RepoPrefill> = {};
+    const lockedRepos = new Set<string>();
+    for (const repo of catalog) {
+      const repoPath = join(workspacePath, repo.name);
+      if (!existsSync(join(repoPath, ".git"))) continue;
+      lockedRepos.add(repo.name);
+      prefills[repo.name] = {
+        already_cloned: true,
+        current_branch: _readCurrentBranch(repoPath),
+      };
+    }
+    return { prefills, lockedRepos };
+  }
+
+  private async _cloneAndCheckout(
+    workspacePath: string,
+    sel: { repo: PredefinedRepo; name: string; branch: string },
+  ): Promise<RepoResult> {
+    const targetPath = join(workspacePath, sel.name);
+    const alreadyCloned = existsSync(join(targetPath, ".git"));
+
+    if (!alreadyCloned) {
+      // Seed the shared object cache (or reuse the existing mirror) so
+      // this clone and every future one for the same repo pays the
+      // network/disk cost of the history at most once. If the cache
+      // can't be established (first-time network failure, disk full,
+      // etc.) we silently fall back to a plain clone — correctness
+      // over space.
+      const mirror = await ensureCachedMirror(sel.repo);
+      const cloneArgs = mirror
+        ? ["clone", "--reference", mirror, sel.repo.git_url, sel.name]
+        : ["clone", sel.repo.git_url, sel.name];
+      const clone = await _execGit(cloneArgs, workspacePath);
+      if (!clone.ok) {
+        return {
+          name: sel.name,
+          branch: sel.branch,
+          status: "clone_failed",
+          detail: clone.stderr || clone.stdout,
+        };
+      }
+    } else {
+      // Fetch so `git checkout <new-branch>` can find branches pushed after
+      // the initial clone. Fetch failures are non-fatal — if the user only
+      // wants to switch between already-known branches, offline is fine.
+      const fetch = await _execGit(
+        ["fetch", "--prune", "origin"],
+        targetPath,
+      );
+      if (!fetch.ok) {
+        this._logger.warn(
+          { repo: sel.name, stderr: fetch.stderr },
+          "git fetch failed before checkout; continuing with stale refs",
+        );
+      }
+    }
+
+    const co = await _execGit(["checkout", sel.branch], targetPath);
+    if (!co.ok) {
+      // Fall back to the branch the repo is currently on so the binding still
+      // has an `active_branch` instead of leaving it blank.
+      const head = await _execGit(
+        ["rev-parse", "--abbrev-ref", "HEAD"],
+        targetPath,
+      );
+      const fallbackBranch = head.ok && head.stdout ? head.stdout : sel.branch;
+      return {
+        name: sel.name,
+        branch: sel.branch,
+        actual_branch: fallbackBranch,
+        status: "checkout_failed",
+        detail: co.stderr || co.stdout,
+      };
+    }
+
+    // After a successful checkout on an already-cloned repo, try a
+    // fast-forward pull so users who re-run /setup without changing the
+    // branch still get the latest commits. `--ff-only` refuses on dirty
+    // trees or divergence, which keeps this safe to run unconditionally.
+    if (alreadyCloned) {
+      const pull = await _execGit(
+        ["pull", "--ff-only", "--no-rebase"],
+        targetPath,
+      );
+      if (!pull.ok) {
+        this._logger.info(
+          { repo: sel.name, stderr: pull.stderr },
+          "ff-only pull skipped/failed; leaving at current commit",
+        );
+      }
+    }
+
+    return {
+      name: sel.name,
+      branch: sel.branch,
+      actual_branch: sel.branch,
+      status: alreadyCloned ? "exists" : "cloned",
+    };
+  }
+
+  private async _replyText(
+    message: UserMessage,
+    text: string,
+  ): Promise<void> {
+    if (!message.channel_id) return;
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) return;
+    await channel.replyMessage(
+      message.id,
+      {
+        role: "assistant",
+        session_id: message.session_id,
+        content: [{ type: "text", text }],
+      },
+      { streaming: false, replyInThread: false },
+    );
+  }
+}
+
+function _isTruthyChecker(v: unknown): boolean {
+  if (v === true) return true;
+  if (typeof v === "string") {
+    const lower = v.toLowerCase();
+    return lower === "true" || lower === "1" || lower === "on";
+  }
+  return false;
+}
+
+function _formatResultLine(r: RepoResult): string {
+  switch (r.status) {
+    case "cloned":
+      return `- ✅ \`${formatRepoRef(r.name, r.branch)}\` 已克隆`;
+    case "exists":
+      return `- ℹ️  \`${formatRepoRef(r.name, r.branch)}\` 已存在`;
+    case "checkout_failed":
+      return (
+        `- ⚠️  \`${r.name}\` 已克隆，分支 \`${r.branch}\` 不可切换，` +
+        `保留在 \`${r.actual_branch ?? "(未知)"}\`` +
+        (r.detail ? `：${_compressDetail(r.detail)}` : "")
+      );
+    case "clone_failed":
+      return `- ❌ \`${r.name}\` 克隆失败${
+        r.detail ? `：${_compressDetail(r.detail)}` : ""
+      }`;
+  }
+}
+
+function _compressDetail(detail: string): string {
+  const first = detail.split("\n").find((l) => l.trim()) ?? "";
+  return first.length > 120 ? first.slice(0, 120) + "…" : first;
+}
+
+/**
+ * Extract the useful bits out of a Feishu/Axios error so we can see the
+ * actual server error code + message in the logs without dumping the whole
+ * request/response graph.
+ */
+function _summarizeFeishuError(
+  err: unknown,
+): { code?: number; msg?: string; status?: number; raw?: unknown } {
+  if (!err || typeof err !== "object") {
+    return { raw: err };
+  }
+  const candidate = err as {
+    response?: {
+      status?: number;
+      data?: { code?: number; msg?: string };
+    };
+    message?: string;
+  };
+  return {
+    code: candidate.response?.data?.code,
+    msg: candidate.response?.data?.msg ?? candidate.message,
+    status: candidate.response?.status,
+  };
+}
+
+/**
+ * Readable-ish short form of a Feishu chat id — used when the group name
+ * is unavailable so the default workspace name is still unique + stable.
+ * Strips the `oc_` prefix (always present on chat ids) and keeps the first
+ * 8 chars of the opaque suffix.
+ */
+function _chatIdFallbackSlug(chatId: string): string {
+  const stripped = chatId.replace(/^oc_/, "");
+  return stripped.slice(0, 8) || "group";
+}
+
+function _readCurrentBranch(repoPath: string): string | undefined {
+  try {
+    const proc = Bun.spawnSync(
+      ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+      { cwd: repoPath, stdout: "pipe", stderr: "pipe" },
+    );
+    if (proc.exitCode !== 0) return undefined;
+    const out = proc.stdout.toString().trim();
+    return out && out !== "HEAD" ? out : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function _execGit(
+  args: string[],
+  cwd: string,
+): Promise<{ ok: boolean; stdout: string; stderr: string; code: number }> {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  return { ok: code === 0, stdout: stdout.trim(), stderr: stderr.trim(), code };
+}
diff --git a/src/kernel/setup/switch-card.ts b/src/kernel/setup/switch-card.ts
new file mode 100644
index 0000000..84bcea6
--- /dev/null
+++ b/src/kernel/setup/switch-card.ts
@@ -0,0 +1,167 @@
+import type { Workspace } from "@/shared";
+
+import type {
+  ButtonElement,
+  Card,
+  Element,
+  FormElement,
+  SelectStaticElement,
+} from "../../community/feishu/messaging/types";
+
+import {
+  buildCardIntro,
+  buildMarkdown,
+  buildResultCard,
+  buildSectionBlock,
+} from "./card-ui";
+
+/**
+ * Shared field names used by both the card renderer and the submit handler.
+ * Keep them in one place so the two sides cannot drift apart.
+ */
+export const SWITCH_FIELD = {
+  workspaceId: "workspace_id",
+} as const;
+
+/**
+ * Sentinel value emitted by the "detach" option. Not a real workspace id —
+ * picking it clears the binding for the current chat and falls back to the
+ * default workspace.
+ */
+export const SWITCH_DETACH_VALUE = "__detach__";
+
+/**
+ * Summary of the current binding, rendered above the selector so the user
+ * can see what they're switching away from before picking.
+ */
+export interface CurrentBindingSummary {
+  workspace_id: string;
+  workspace_name: string;
+  workspace_path: string;
+  active_repo?: string | null;
+  active_branch?: string | null;
+}
+
+export interface SwitchCardOptions {
+  /** All known workspaces, sorted by caller. */
+  workspaces: Workspace[];
+  /** Current binding for this chat; preselects the dropdown + shows summary. */
+  current?: CurrentBindingSummary;
+}
+
+/**
+ * Build the `/switch` card with a richer structure than the old plain
+ * markdown version: card head, current-binding summary, and a clearer form
+ * section that explains the detach option.
+ */
+export function buildSwitchCard(options: SwitchCardOptions): Card {
+  const { workspaces, current } = options;
+
+  const body: Element[] = [
+    buildCardIntro({
+      title: "切换 Workspace",
+    }),
+  ];
+
+  if (current) {
+    body.push(...buildSectionBlock({
+      title: "当前绑定",
+      lines: [
+        `- 名称：\`${current.workspace_name}\``,
+        `- ID：\`${current.workspace_id}\``,
+        `- 活跃仓库：\`${current.active_repo ?? "(未设置)"}\``,
+        `- 活跃分支：\`${current.active_branch ?? "(未设置)"}\``,
+      ],
+    }));
+  } else {
+    body.push(...buildSectionBlock({
+      title: "当前绑定",
+      lines: ["- 当前会话未绑定 workspace"],
+    }));
+  }
+
+  const select = _buildWorkspaceSelect(workspaces, current?.workspace_id);
+  const submit = _buildSubmitButton();
+  const form: FormElement = {
+    tag: "form",
+    name: "switch_form",
+    elements: [
+      buildMarkdown("**目标 Workspace**"),
+      select,
+      submit,
+    ],
+  };
+  body.push(form);
+
+  return {
+    schema: "2.0",
+    config: {
+      streaming_mode: false,
+      update_multi: true,
+      width_mode: "fill",
+      summary: { content: "🔀 切换 workspace" },
+    },
+    body: {
+      padding: "12px 16px 16px 16px",
+      vertical_spacing: "12px",
+      elements: body,
+    },
+  };
+}
+
+/**
+ * Result card rendered after the submit handler finishes. Replaces the
+ * original card in place via `updateRawCard`.
+ */
+export function buildSwitchResultCard(summary: string, detail: string[] = []): Card {
+  return buildResultCard({
+    title: "Workspace 切换结果",
+    summary,
+    detail,
+  });
+}
+
+function _buildWorkspaceSelect(
+  workspaces: Workspace[],
+  preselected?: string,
+): SelectStaticElement {
+  const options = workspaces.map((ws) => ({
+    text: {
+      tag: "plain_text" as const,
+      content: `${ws.name}  (${ws.id})`,
+    },
+    value: ws.id,
+  }));
+  options.push({
+    text: {
+      tag: "plain_text" as const,
+      content: "🔌 取消绑定（回到默认 workspace）",
+    },
+    value: SWITCH_DETACH_VALUE,
+  });
+
+  const initial =
+    preselected && workspaces.some((ws) => ws.id === preselected)
+      ? preselected
+      : options[0]?.value;
+
+  return {
+    tag: "select_static",
+    name: SWITCH_FIELD.workspaceId,
+    placeholder: { tag: "plain_text", content: "选择一个 workspace" },
+    initial_option: initial,
+    options,
+    width: "fill",
+  };
+}
+
+function _buildSubmitButton(): ButtonElement {
+  return {
+    tag: "button",
+    name: "switch_submit",
+    text: { tag: "plain_text", content: "确认切换" },
+    type: "primary",
+    action_type: "form_submit",
+    width: "fill",
+  };
+}
diff --git a/src/kernel/setup/switch-flow.ts b/src/kernel/setup/switch-flow.ts
new file mode 100644
index 0000000..591c795
--- /dev/null
+++ b/src/kernel/setup/switch-flow.ts
@@ -0,0 +1,282 @@
+import { join } from "node:path";
+
+import type { Logger } from "@/shared";
+import {
+  createLogger,
+  type CardActionPayload,
+  type UserMessage,
+} from "@/shared";
+
+import type { FeishuMessageChannel } from "../../community/feishu/messaging/message-channel";
+import { readRepoHead, type GroupWorkspaceStore } from "../workspaces";
+
+import {
+  buildSwitchCard,
+  buildSwitchResultCard,
+  SWITCH_DETACH_VALUE,
+  SWITCH_FIELD,
+} from "./switch-card";
+
+/**
+ * In-memory pending state for a `/switch` card that has been sent but not
+ * yet submitted. Dropped on kernel restart — expired cards surface a clear
+ * error back to the user instead of being silently honored.
+ */
+interface PendingSwitch {
+  chat_id: string;
+  initiator_open_id: string;
+  /** Snapshot of valid workspace ids at card-render time, for validation on submit. */
+  valid_workspace_ids: Set<string>;
+  created_at: number;
+}
+
+/**
+ * Stateful orchestrator for the `/switch` interactive flow.
+ *
+ * Lifecycle:
+ * 1. `start(message)` lists all known workspaces, renders the card, and
+ *    remembers the id snapshot keyed by the outbound message id.
+ * 2. The kernel routes a `card:action` with `action_name === "switch_submit"`
+ *    to `handleSubmit(payload)`.
+ * 3. The handler applies the binding change (switch or detach) and replaces
+ *    the card in place with a result card.
+ *
+ * Unlike `/setup`, `/switch` is available in both group chats and single
+ * chats (P2P) — its only job is re-pointing the chat's binding at an
+ * already-existing workspace, no filesystem mutation.
+ */
+export class SwitchFlow {
+  private readonly _logger: Logger = createLogger("switch-flow");
+  private readonly _workspaceStore: GroupWorkspaceStore;
+  private readonly _feishuChannels: Map<string, FeishuMessageChannel>;
+  private readonly _pending = new Map<string, PendingSwitch>();
+
+  constructor(deps: {
+    workspaceStore: GroupWorkspaceStore;
+    feishuChannels: Map<string, FeishuMessageChannel>;
+  }) {
+    this._workspaceStore = deps.workspaceStore;
+    this._feishuChannels = deps.feishuChannels;
+  }
+
+  /**
+   * Entry point invoked from `kernel._handleInboundMessage` when the inbound
+   * text is `/switch`. Works in both group and P2P Feishu chats since the
+   * binding is keyed purely on `chat_id`.
+   */
+  async start(message: UserMessage): Promise<void> {
+    const chatId = message.chat_id;
+    if (!chatId || !message.channel_id) {
+      await this._replyText(
+        message,
+        "❌ /switch 需要飞书会话上下文（群聊或单聊均可）。",
+      );
+      return;
+    }
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) {
+      await this._replyText(message, "❌ 无法找到对应的飞书 channel。");
+      return;
+    }
+
+    const workspaces = this._workspaceStore.listWorkspaces();
+    if (workspaces.length === 0) {
+      await this._replyText(
+        message,
+        [
+          "ℹ️  还没有任何 workspace。",
+          "请先在某个群里执行 `/setup` 创建一个，然后回到这里 `/switch` 挑选。",
+        ].join("\n"),
+      );
+      return;
+    }
+
+    const current = this._workspaceStore.getBinding(chatId);
+    const sortedWorkspaces = [...workspaces].sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+    const card = buildSwitchCard({
+      workspaces: sortedWorkspaces,
+      current: current
+        ? {
+            workspace_id: current.workspace_id,
+            workspace_name: current.workspace_name,
+            workspace_path: current.workspace_path,
+            active_repo: current.active_repo,
+            active_branch: current.active_repo
+              ? readRepoHead(join(current.workspace_path, current.active_repo)) ??
+                null
+              : null,
+          }
+        : undefined,
+    });
+    const cardMessageId = await channel.sendRawCard(chatId, card, {
+      replyTo: message.id,
+    });
+    this._pending.set(cardMessageId, {
+      chat_id: chatId,
+      initiator_open_id: message.sender_open_id ?? "",
+      valid_workspace_ids: new Set(sortedWorkspaces.map((ws) => ws.id)),
+      created_at: Date.now(),
+    });
+    this._logger.info(
+      {
+        chat_id: chatId,
+        card_message_id: cardMessageId,
+        workspace_count: sortedWorkspaces.length,
+      },
+      "switch card sent",
+    );
+  }
+
+  /**
+   * Entry point invoked from the kernel's `card:action` listener when the
+   * payload's `action_name === "switch_submit"`. Looks up pending state by
+   * `payload.message_id`, validates, and applies the binding change.
+   */
+  async handleSubmit(payload: CardActionPayload): Promise<void> {
+    const channel = this._feishuChannels.get(payload.channel_id);
+    if (!channel) {
+      this._logger.warn(
+        { channel_id: payload.channel_id },
+        "received switch card action for unknown channel",
+      );
+      return;
+    }
+    const pending = this._pending.get(payload.message_id);
+    if (!pending) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSwitchResultCard("⚠️  这张卡片已失效，请重新发送 `/switch`。"),
+        "expired",
+      );
+      return;
+    }
+    if (
+      pending.initiator_open_id &&
+      payload.operator_open_id !== pending.initiator_open_id
+    ) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSwitchResultCard("🚫 这不是你的表单。"),
+        "non-initiator",
+      );
+      return;
+    }
+
+    this._pending.delete(payload.message_id);
+
+    const rawPick = payload.form_value[SWITCH_FIELD.workspaceId];
+    const pick = typeof rawPick === "string" ? rawPick : "";
+
+    if (pick === SWITCH_DETACH_VALUE) {
+      const removed = this._workspaceStore.deleteBinding(pending.chat_id);
+      const msg = removed
+        ? "✅ 已取消绑定，当前会话回到默认 workspace。"
+        : "ℹ️  当前会话本来就没有绑定，回到默认 workspace。";
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSwitchResultCard(msg),
+        "detached",
+      );
+      this._logger.info(
+        { chat_id: pending.chat_id, removed },
+        "switch card: detached",
+      );
+      return;
+    }
+
+    if (!pick || !pending.valid_workspace_ids.has(pick)) {
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSwitchResultCard(
+          "⚠️  选择的 workspace 已不存在，请重新发送 `/switch`。",
+        ),
+        "invalid-selection",
+      );
+      return;
+    }
+
+    let binding;
+    try {
+      binding = this._workspaceStore.upsertBinding(pending.chat_id, {
+        workspace_id: pick,
+      });
+    } catch (err) {
+      this._logger.error(
+        { err, chat_id: pending.chat_id, workspace_id: pick },
+        "switch card: upsertBinding failed",
+      );
+      await this._tryUpdateCard(
+        channel,
+        payload.message_id,
+        buildSwitchResultCard(
+          `❌ 绑定失败：${(err as Error).message}`,
+        ),
+        "upsert-failed",
+      );
+      return;
+    }
+
+    const summary = `✅ 已切换到 workspace \`${binding.workspace_name}\`。`;
+    // Show the on-disk HEAD of the target workspace's active repo, not the
+    // stored `active_branch` — switching only rebinds; the repo keeps its
+    // current checkout.
+    const headBranch = binding.active_repo
+      ? readRepoHead(join(binding.workspace_path, binding.active_repo))
+      : undefined;
+    const detail = [
+      `- Workspace ID：\`${binding.workspace_id}\``,
+      `- 活跃仓库：\`${binding.active_repo ?? "(未设置)"}\``,
+      `- 活跃分支：\`${headBranch ?? "(未设置)"}\``,
+    ];
+    await this._tryUpdateCard(
+      channel,
+      payload.message_id,
+      buildSwitchResultCard(summary, detail),
+      "final-result",
+    );
+    this._logger.info(
+      { chat_id: pending.chat_id, workspace_id: binding.workspace_id },
+      "switch card: binding updated",
+    );
+  }
+
+  private async _tryUpdateCard(
+    channel: FeishuMessageChannel,
+    messageId: string,
+    card: ReturnType<typeof buildSwitchResultCard>,
+    stage: string,
+  ): Promise<void> {
+    try {
+      await channel.updateRawCard(messageId, card);
+    } catch (err) {
+      this._logger.error(
+        { err, stage, message_id: messageId },
+        "updateRawCard failed",
+      );
+    }
+  }
+
+  private async _replyText(
+    message: UserMessage,
+    text: string,
+  ): Promise<void> {
+    if (!message.channel_id) return;
+    const channel = this._feishuChannels.get(message.channel_id);
+    if (!channel) return;
+    await channel.replyMessage(
+      message.id,
+      {
+        role: "assistant",
+        session_id: message.session_id,
+        content: [{ type: "text", text }],
+      },
+      { streaming: false, replyInThread: false },
+    );
+  }
+}
diff --git a/src/kernel/tasking/task-dispatcher.ts b/src/kernel/tasking/task-dispatcher.ts
index 529a244..f365f67 100644
--- a/src/kernel/tasking/task-dispatcher.ts
+++ b/src/kernel/tasking/task-dispatcher.ts
@@ -630,11 +630,21 @@ export class TaskDispatcher {
   /**
    * Process a job from the queue. Acquires a per-session lock so that
    * tasks for the same session_id execute serially in FIFO order.
+   *
+   * The serial gate is decoupled from each task's success/failure on
+   * purpose: a failing task still throws (so bunqueue records the failure
+   * and the handler's failure reply reaches the user), but the promise we
+   * publish as the session's lock tail is a *swallowed* view. Otherwise a
+   * single rejection would poison the chain — `.then(onFulfilled)` on the
+   * next task would skip its handler, leaving every later message stuck
+   * "pending" until process restart.
    */
   private async _processJob(job: Job<TaskJobData>): Promise<void> {
     const { payload } = job.data;
     const sessionId = job.data.session_id ?? uuid();
 
+    // `previous` is always a swallowed tail (see below), so it resolves
+    // regardless of how the predecessor finished — the next handler runs.
     const previous = this._sessionLocks.get(sessionId) ?? Promise.resolve();
 
     const current = previous.then(async () => {
@@ -687,11 +697,21 @@ export class TaskDispatcher {
       }
     });
 
-    this._sessionLocks.set(sessionId, current);
-    await current;
+    // Publish a swallowed view as the lock tail so a failure in `current`
+    // can never reject the chain the next task waits on. Keep the handle
+    // for the identity check in cleanup.
+    const tail = current.catch(() => {});
+    this._sessionLocks.set(sessionId, tail);
 
-    if (this._sessionLocks.get(sessionId) === current) {
-      this._sessionLocks.delete(sessionId);
+    try {
+      // Re-throw this task's own failure so bunqueue marks the job failed
+      // and retries per config; successors are unaffected (they chain on
+      // `tail`, not `current`).
+      await current;
+    } finally {
+      if (this._sessionLocks.get(sessionId) === tail) {
+        this._sessionLocks.delete(sessionId);
+      }
     }
   }
 
diff --git a/src/kernel/workspaces/git-cache.ts b/src/kernel/workspaces/git-cache.ts
new file mode 100644
index 0000000..57e5912
--- /dev/null
+++ b/src/kernel/workspaces/git-cache.ts
@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { config, createLogger } from "@/shared";
+
+const _logger = createLogger("git-cache");
+
+/**
+ * On-disk object cache used as the `--reference` source when cloning
+ * predefined repos into workspaces. Each entry is a bare mirror
+ * (`git clone --mirror`) living at `$AGENTARA_HOME/git-cache/<name>.git/`,
+ * maintained exclusively by agentara — users don't check out, commit,
+ * or run `git gc` inside these mirrors, so the `--reference` dependents
+ * can't have their objects pulled out from under them.
+ *
+ * Cache loss is survivable: callers fall back to a plain clone when
+ * `ensureCachedMirror` returns `null`, so a broken or absent cache just
+ * turns into "every clone is full again" — slow, but still correct.
+ */
+
+export interface GitCacheOptions {
+  /** Override the cache root (tests). Defaults to `config.paths.git_cache`. */
+  cacheRoot?: string;
+  /** Per-git-process timeout in ms. Defaults to 5 minutes. */
+  timeoutMs?: number;
+}
+
+const DEFAULT_CLONE_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_FETCH_TIMEOUT_MS = 2 * 60 * 1000;
+
+/**
+ * In-flight ensure operations keyed by absolute mirror path. Lets two
+ * concurrent chats that first-touch the same repo share a single clone
+ * process instead of racing on the target directory (the second clone
+ * would fail with "destination path exists").
+ */
+const _inflight = new Map<string, Promise<string | null>>();
+
+/**
+ * Absolute path where the mirror for a given repo name lives, whether
+ * or not it currently exists on disk.
+ */
+export function cachedMirrorPath(
+  repoName: string,
+  options: Pick<GitCacheOptions, "cacheRoot"> = {},
+): string {
+  const root = options.cacheRoot ?? config.paths.git_cache;
+  return join(root, `${repoName}.git`);
+}
+
+/**
+ * Lazily ensure a bare mirror exists for the given repo. Returns the
+ * mirror path on success, or `null` on clone failure so callers can
+ * decide whether to fall back. Concurrent calls for the same name
+ * share a single clone process.
+ */
+export async function ensureCachedMirror(
+  repo: { name: string; git_url: string },
+  options: GitCacheOptions = {},
+): Promise<string | null> {
+  const mirror = cachedMirrorPath(repo.name, options);
+  if (existsSync(mirror)) return mirror;
+
+  const inflight = _inflight.get(mirror);
+  if (inflight) return inflight;
+
+  const task = _doClone(repo, mirror, options).finally(() => {
+    _inflight.delete(mirror);
+  });
+  _inflight.set(mirror, task);
+  return task;
+}
+
+/**
+ * Best-effort `git fetch` on an existing mirror. No-op when the mirror
+ * doesn't exist. Returns `true` on success, `false` on failure or
+ * missing mirror; caller decides whether to surface to the user.
+ */
+export async function refreshCachedMirror(
+  repoName: string,
+  options: GitCacheOptions = {},
+): Promise<boolean> {
+  const mirror = cachedMirrorPath(repoName, options);
+  if (!existsSync(mirror)) return false;
+  const timeout = options.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+  const res = await _execGit(["fetch", "--prune"], mirror, timeout);
+  if (!res.ok) {
+    _logger.warn(
+      { repo: repoName, mirror, stderr: res.stderr },
+      "cache mirror fetch failed",
+    );
+  }
+  return res.ok;
+}
+
+async function _doClone(
+  repo: { name: string; git_url: string },
+  mirror: string,
+  options: GitCacheOptions,
+): Promise<string | null> {
+  const root = options.cacheRoot ?? config.paths.git_cache;
+  if (!existsSync(root)) mkdirSync(root, { recursive: true });
+  const timeout = options.timeoutMs ?? DEFAULT_CLONE_TIMEOUT_MS;
+  _logger.info({ repo: repo.name, mirror }, "seeding cache mirror");
+  const res = await _execGit(
+    ["clone", "--mirror", repo.git_url, `${repo.name}.git`],
+    root,
+    timeout,
+  );
+  if (!res.ok) {
+    _logger.warn(
+      { repo: repo.name, stderr: res.stderr },
+      "cache mirror clone failed; caller will fall back to direct clone",
+    );
+    // Git may leave a partial dir behind on failure; wipe it so the
+    // next attempt starts from a clean state instead of tripping over
+    // "destination path already exists".
+    try {
+      if (existsSync(mirror)) rmSync(mirror, { recursive: true, force: true });
+    } catch (err) {
+      _logger.warn({ err, mirror }, "failed to clean up partial mirror dir");
+    }
+    return null;
+  }
+  return mirror;
+}
+
+async function _execGit(
+  args: string[],
+  cwd: string,
+  timeoutMs: number,
+): Promise<{ ok: boolean; stdout: string; stderr: string; code: number }> {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const timer = setTimeout(() => {
+    try {
+      proc.kill();
+    } catch {
+      // process may already be gone
+    }
+  }, timeoutMs);
+  try {
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const code = await proc.exited;
+    return {
+      ok: code === 0,
+      stdout: stdout.trim(),
+      stderr: stderr.trim(),
+      code,
+    };
+  } catch (err) {
+    return { ok: false, stdout: "", stderr: String(err), code: -1 };
+  } finally {
+    clearTimeout(timer);
+  }
+}
diff --git a/src/kernel/workspaces/git-sync.ts b/src/kernel/workspaces/git-sync.ts
new file mode 100644
index 0000000..3bddcf2
--- /dev/null
+++ b/src/kernel/workspaces/git-sync.ts
@@ -0,0 +1,445 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { createLogger } from "@/shared";
+
+import { refreshCachedMirror } from "./git-cache";
+
+const _logger = createLogger("git-sync");
+
+export interface RepoSyncState {
+  /** Repo directory name under the workspace root. */
+  name: string;
+  /** Absolute path to the repo. */
+  path: string;
+  /** Current branch; `undefined` for detached HEAD. */
+  branch?: string;
+  /** Name of the upstream branch (e.g. `origin/master`), when configured. */
+  upstream?: string;
+  /** Commits on the local branch not yet on upstream. */
+  ahead: number;
+  /** Commits on upstream not yet on the local branch. */
+  behind: number;
+  /** True when the working tree has uncommitted changes. */
+  dirty: boolean;
+}
+
+export type PullStatus =
+  /** `git fetch` + `git pull --ff-only` succeeded (may be a no-op if already up-to-date). */
+  | "up_to_date"
+  | "fast_forwarded"
+  /** Fetch worked but pull was skipped because the tree was dirty or diverged. */
+  | "skipped_dirty"
+  | "skipped_diverged"
+  /** No upstream configured — there's nothing to pull from. */
+  | "no_upstream"
+  /** Detached HEAD — there's no branch to pull into. */
+  | "detached"
+  /** The network / `git` process failed. */
+  | "fetch_failed"
+  | "pull_failed";
+
+export interface RepoSyncResult {
+  name: string;
+  path: string;
+  branch?: string;
+  /** Ahead/behind after the (attempted) sync, so /sync output reflects current truth. */
+  ahead: number;
+  behind: number;
+  status: PullStatus;
+  /** Short commit SHAs before/after on status `fast_forwarded`. */
+  before_sha?: string;
+  after_sha?: string;
+  /** Short human-readable detail on failure/skip paths. */
+  detail?: string;
+}
+
+export interface SyncOptions {
+  /**
+   * Whether to attempt `git pull --ff-only` after fetch. When false, only the
+   * fetch is performed and ahead/behind is refreshed without touching the
+   * working tree. Defaults to true.
+   */
+  pull?: boolean;
+  /**
+   * Per-repo timeout budget in ms. Individual git processes get at most this
+   * long before we kill them and record a failure — keeps a flaky network
+   * from hanging session start forever. Defaults to 20_000.
+   */
+  timeout_ms?: number;
+}
+
+/**
+ * Fire a fetch + optional ff-only pull for every git repo under `workspacePath`.
+ * Safe to run concurrently with an active agent: fetch never touches the
+ * working tree, and ff-only pull is atomic and refuses to run on dirty /
+ * diverged repos. Returns one result per repo — callers decide how to
+ * format (e.g. /sync writes a summary; session-start logs silently).
+ */
+export async function syncWorkspace(
+  workspacePath: string,
+  options: SyncOptions = {},
+): Promise<RepoSyncResult[]> {
+  const repos = listRepos(workspacePath);
+  const results: RepoSyncResult[] = [];
+  for (const repo of repos) {
+    results.push(await syncRepo(repo.path, options));
+  }
+  return results;
+}
+
+/**
+ * Sync a single repo. See {@link syncWorkspace} for semantics.
+ */
+export async function syncRepo(
+  repoPath: string,
+  options: SyncOptions = {},
+): Promise<RepoSyncResult> {
+  const pull = options.pull !== false;
+  const timeout = options.timeout_ms ?? 20_000;
+  const name = _basename(repoPath);
+  const branch = await _readCurrentBranch(repoPath);
+
+  const fetch = await _execGit(
+    ["fetch", "--prune", "origin"],
+    repoPath,
+    timeout,
+  );
+  if (!fetch.ok) {
+    const state = await _readState(repoPath);
+    return {
+      name,
+      path: repoPath,
+      branch,
+      ahead: state.ahead,
+      behind: state.behind,
+      status: "fetch_failed",
+      detail: _compressErr(fetch.stderr || fetch.stdout),
+    };
+  }
+
+  // Keep the shared object cache fresh so future `--reference` clones
+  // of this repo hit recent commits instead of re-downloading them.
+  // No-op when no cache mirror exists for this name. Best-effort —
+  // any failure is logged inside refreshCachedMirror and doesn't
+  // impact the workspace sync result.
+  await refreshCachedMirror(name, { timeoutMs: timeout });
+
+  if (!branch) {
+    const state = await _readState(repoPath);
+    return {
+      name,
+      path: repoPath,
+      ahead: state.ahead,
+      behind: state.behind,
+      status: "detached",
+    };
+  }
+
+  const upstream = await _readUpstream(repoPath);
+  if (!upstream) {
+    return {
+      name,
+      path: repoPath,
+      branch,
+      ahead: 0,
+      behind: 0,
+      status: "no_upstream",
+    };
+  }
+
+  const state = await _readState(repoPath);
+
+  if (!pull) {
+    return {
+      name,
+      path: repoPath,
+      branch,
+      ahead: state.ahead,
+      behind: state.behind,
+      status: state.behind === 0 ? "up_to_date" : "up_to_date",
+    };
+  }
+
+  if (state.dirty) {
+    return {
+      name,
+      path: repoPath,
+      branch,
+      ahead: state.ahead,
+      behind: state.behind,
+      status: "skipped_dirty",
+      detail: "working tree has uncommitted changes",
+    };
+  }
+  if (state.ahead > 0 && state.behind > 0) {
+    return {
+      name,
+      path: repoPath,
+      branch,
+      ahead: state.ahead,
+      behind: state.behind,
+      status: "skipped_diverged",
+      detail: `local has ${state.ahead} commit(s) not on upstream`,
+    };
+  }
+  if (state.behind === 0) {
+    return {
+      name,
+      path: repoPath,
+      branch,
+      ahead: state.ahead,
+      behind: 0,
+      status: "up_to_date",
+    };
+  }
+
+  const before = await _readHeadSha(repoPath);
+  const pullRes = await _execGit(
+    ["pull", "--ff-only", "--no-rebase"],
+    repoPath,
+    timeout,
+  );
+  if (!pullRes.ok) {
+    return {
+      name,
+      path: repoPath,
+      branch,
+      ahead: state.ahead,
+      behind: state.behind,
+      status: "pull_failed",
+      detail: _compressErr(pullRes.stderr || pullRes.stdout),
+    };
+  }
+  const after = await _readHeadSha(repoPath);
+  const postState = await _readState(repoPath);
+  return {
+    name,
+    path: repoPath,
+    branch,
+    ahead: postState.ahead,
+    behind: postState.behind,
+    status: "fast_forwarded",
+    before_sha: before,
+    after_sha: after,
+  };
+}
+
+/**
+ * Read the sync state of every git repo under `workspacePath` without doing
+ * any network work. Used by `/status` to render the ahead/behind indicators
+ * from the most recent fetch's locally-known upstream refs.
+ */
+export function listRepoSyncState(workspacePath: string): RepoSyncState[] {
+  return listRepos(workspacePath).map((r) => {
+    const branch = _readCurrentBranchSync(r.path);
+    const upstream = _readUpstreamSync(r.path);
+    const ahead = upstream ? _readAheadSync(r.path) : 0;
+    const behind = upstream ? _readBehindSync(r.path) : 0;
+    const dirty = _readDirtySync(r.path);
+    return {
+      name: r.name,
+      path: r.path,
+      branch,
+      upstream,
+      ahead,
+      behind,
+      dirty,
+    };
+  });
+}
+
+/**
+ * Read the current branch of a single repo (HEAD). Returns `undefined` when
+ * the repo is in a detached-HEAD state or git exits non-zero. Thin wrapper
+ * around the internal sync helper so other layers don't have to shell out
+ * themselves.
+ */
+export function readRepoHead(repoPath: string): string | undefined {
+  return _readCurrentBranchSync(repoPath);
+}
+
+/**
+ * Render `↑a ↓b` for ahead/behind counts, omitting zero sides. Returns an
+ * empty string when both sides are zero. Callers usually concatenate this
+ * after a `repo branch` code block.
+ */
+export function formatAheadBehind(ahead: number, behind: number): string {
+  const parts: string[] = [];
+  if (ahead > 0) parts.push(`↑${ahead}`);
+  if (behind > 0) parts.push(`↓${behind}`);
+  return parts.join(" ");
+}
+
+function listRepos(
+  workspacePath: string,
+): Array<{ name: string; path: string }> {
+  if (!existsSync(workspacePath)) return [];
+  try {
+    return readdirSync(workspacePath)
+      .filter((name) => !name.startsWith("."))
+      .map((name) => ({ name, path: join(workspacePath, name) }))
+      .filter((r) => {
+        try {
+          return statSync(r.path).isDirectory() && existsSync(join(r.path, ".git"));
+        } catch {
+          return false;
+        }
+      })
+      .sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+}
+
+async function _execGit(
+  args: string[],
+  cwd: string,
+  timeoutMs: number,
+): Promise<{ ok: boolean; stdout: string; stderr: string; code: number }> {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const timer = setTimeout(() => {
+    try {
+      proc.kill();
+    } catch {
+      // ignore — process may already be gone
+    }
+  }, timeoutMs);
+  try {
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    const code = await proc.exited;
+    return {
+      ok: code === 0,
+      stdout: stdout.trim(),
+      stderr: stderr.trim(),
+      code,
+    };
+  } catch (err) {
+    _logger.warn({ err, args, cwd }, "git exec threw");
+    return { ok: false, stdout: "", stderr: String(err), code: -1 };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function _readCurrentBranch(repoPath: string): Promise<string | undefined> {
+  const res = await _execGit(
+    ["rev-parse", "--abbrev-ref", "HEAD"],
+    repoPath,
+    5000,
+  );
+  if (!res.ok) return undefined;
+  const out = res.stdout;
+  return out && out !== "HEAD" ? out : undefined;
+}
+
+async function _readUpstream(repoPath: string): Promise<string | undefined> {
+  const res = await _execGit(
+    ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+    repoPath,
+    5000,
+  );
+  return res.ok && res.stdout ? res.stdout : undefined;
+}
+
+async function _readHeadSha(repoPath: string): Promise<string | undefined> {
+  const res = await _execGit(["rev-parse", "--short=12", "HEAD"], repoPath, 5000);
+  return res.ok ? res.stdout : undefined;
+}
+
+async function _readState(
+  repoPath: string,
+): Promise<{ ahead: number; behind: number; dirty: boolean }> {
+  const counts = await _execGit(
+    ["rev-list", "--left-right", "--count", "HEAD...@{u}"],
+    repoPath,
+    5000,
+  );
+  let ahead = 0;
+  let behind = 0;
+  if (counts.ok) {
+    const [a, b] = counts.stdout.split(/\s+/);
+    ahead = parseInt(a ?? "0", 10) || 0;
+    behind = parseInt(b ?? "0", 10) || 0;
+  }
+  const dirtyRes = await _execGit(
+    ["status", "--porcelain"],
+    repoPath,
+    5000,
+  );
+  const dirty = dirtyRes.ok && dirtyRes.stdout.length > 0;
+  return { ahead, behind, dirty };
+}
+
+function _execGitSync(
+  args: string[],
+  cwd: string,
+): { ok: boolean; stdout: string } {
+  try {
+    const proc = Bun.spawnSync(["git", ...args], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const stdout = proc.stdout.toString().trim();
+    return { ok: proc.exitCode === 0, stdout };
+  } catch {
+    return { ok: false, stdout: "" };
+  }
+}
+
+function _readCurrentBranchSync(repoPath: string): string | undefined {
+  const res = _execGitSync(
+    ["rev-parse", "--abbrev-ref", "HEAD"],
+    repoPath,
+  );
+  if (!res.ok) return undefined;
+  return res.stdout && res.stdout !== "HEAD" ? res.stdout : undefined;
+}
+
+function _readUpstreamSync(repoPath: string): string | undefined {
+  const res = _execGitSync(
+    ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+    repoPath,
+  );
+  return res.ok && res.stdout ? res.stdout : undefined;
+}
+
+function _readAheadSync(repoPath: string): number {
+  const res = _execGitSync(
+    ["rev-list", "--count", "@{u}..HEAD"],
+    repoPath,
+  );
+  return res.ok ? parseInt(res.stdout, 10) || 0 : 0;
+}
+
+function _readBehindSync(repoPath: string): number {
+  const res = _execGitSync(
+    ["rev-list", "--count", "HEAD..@{u}"],
+    repoPath,
+  );
+  return res.ok ? parseInt(res.stdout, 10) || 0 : 0;
+}
+
+function _readDirtySync(repoPath: string): boolean {
+  const res = _execGitSync(["status", "--porcelain"], repoPath);
+  return res.ok && res.stdout.length > 0;
+}
+
+function _basename(p: string): string {
+  const trimmed = p.replace(/[\\/]+$/, "");
+  const idx = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+  return idx >= 0 ? trimmed.slice(idx + 1) : trimmed;
+}
+
+function _compressErr(detail: string): string {
+  const first = detail.split("\n").find((l) => l.trim()) ?? "";
+  return first.length > 160 ? first.slice(0, 160) + "…" : first;
+}
diff --git a/src/kernel/workspaces/index.ts b/src/kernel/workspaces/index.ts
new file mode 100644
index 0000000..1accd65
--- /dev/null
+++ b/src/kernel/workspaces/index.ts
@@ -0,0 +1,3 @@
+export * from "./git-cache";
+export * from "./git-sync";
+export * from "./store";
diff --git a/src/kernel/workspaces/store.ts b/src/kernel/workspaces/store.ts
new file mode 100644
index 0000000..add23ab
--- /dev/null
+++ b/src/kernel/workspaces/store.ts
@@ -0,0 +1,660 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join, sep } from "node:path";
+
+import dayjs from "dayjs";
+import { eq, inArray, like, or } from "drizzle-orm";
+
+import type { DrizzleDB } from "@/data";
+import { groupWorkspaces, sessions, workspaces } from "@/kernel/sessioning/data";
+import { tasks } from "@/kernel/tasking/data";
+import { config, createLogger, uuid, type GroupWorkspace, type Workspace } from "@/shared";
+
+import { readRepoHead } from "./git-sync";
+
+const META_FILE_NAME = "AGENTARA.md";
+
+/**
+ * Resolution result for a group's dispatch context: the cwd to spawn the
+ * runner in plus any env extras (primary repo hint) derived from the active
+ * binding. When `chatId` is unbound, callers fall back to the default
+ * workspace and empty envExtras.
+ */
+export interface WorkspaceResolution {
+  cwd: string;
+  envExtras: Record<string, string>;
+  binding: GroupWorkspace | null;
+}
+
+/**
+ * CRUD + resolution over the `group_workspaces` table. Single-writer; no
+ * caching. Callers should treat results as a snapshot for one dispatch.
+ */
+export class GroupWorkspaceStore {
+  private readonly _logger = createLogger("group-workspace-store");
+  private readonly _db: DrizzleDB;
+
+  constructor(db: DrizzleDB) {
+    this._db = db;
+  }
+
+  /**
+   * Ensure the default workspace root + `_default` fallback both exist, and
+   * migrate any legacy workspace rows whose on-disk path is not yet keyed by
+   * their stable id. Idempotent; safe to call on every boot.
+   */
+  ensureBaseDirs(): void {
+    for (const dir of [config.paths.workspaces, config.paths.default_workspace]) {
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        this._logger.info(`Created workspace dir: ${dir}`);
+      }
+    }
+    this._normalizeWorkspacePaths();
+  }
+
+  /** Fetch the binding for a Feishu chat, or null when none. */
+  getBinding(chatId: string): GroupWorkspace | null {
+    const row = this._db
+      .select()
+      .from(groupWorkspaces)
+      .innerJoin(workspaces, eq(groupWorkspaces.workspace_id, workspaces.id))
+      .where(eq(groupWorkspaces.chat_id, chatId))
+      .get();
+    return row ? this._mapJoinedBinding(row) : null;
+  }
+
+  /** List all bindings, most recently updated first. */
+  listBindings(): GroupWorkspace[] {
+    return this._db
+      .select()
+      .from(groupWorkspaces)
+      .innerJoin(workspaces, eq(groupWorkspaces.workspace_id, workspaces.id))
+      .all()
+      .map((row) => this._mapJoinedBinding(row));
+  }
+
+  /** Fetch a workspace by stable id. */
+  getWorkspace(workspaceId: string): Workspace | null {
+    const row = this._db
+      .select()
+      .from(workspaces)
+      .where(eq(workspaces.id, workspaceId))
+      .get();
+    return row ?? null;
+  }
+
+  /** List all known workspaces. */
+  listWorkspaces(): Workspace[] {
+    return this._db.select().from(workspaces).all();
+  }
+
+  /**
+   * Upsert the binding for a chat. Creates the row if absent; otherwise
+   * merges non-undefined fields over the existing row.
+   *
+   * `workspace_path`/`workspace_name` are only honored when the workspace is
+   * being created (no `workspace_id` supplied and no existing binding that
+   * points at one); once a workspace exists, its identity is owned by the
+   * workspace record. `active_repo`/`active_branch` always go to the
+   * workspace, so groups sharing it see the same active state.
+   */
+  upsertBinding(
+    chatId: string,
+    patch: {
+      active_repo?: string | null;
+      active_branch?: string | null;
+      workspace_id?: string;
+      workspace_name?: string;
+      workspace_path?: string;
+    },
+  ): GroupWorkspace {
+    const now = Date.now();
+    const existing = this.getBinding(chatId);
+    const workspace = this._resolveWorkspace(chatId, existing, patch, now);
+
+    // Active repo/branch live on the workspace — apply any non-undefined
+    // patch values there. If the workspace was just created, it carries the
+    // caller's active_repo/active_branch directly; for existing workspaces
+    // we write through so shared bindings all see the update.
+    const wsActiveRepo =
+      patch.active_repo === undefined ? workspace.active_repo : patch.active_repo;
+    const wsActiveBranch =
+      patch.active_branch === undefined
+        ? workspace.active_branch
+        : patch.active_branch;
+    const wsNameChanged =
+      patch.workspace_name !== undefined &&
+      patch.workspace_name !== workspace.name;
+    const wsActiveChanged =
+      wsActiveRepo !== workspace.active_repo ||
+      wsActiveBranch !== workspace.active_branch;
+    if (wsActiveChanged || wsNameChanged) {
+      this._db
+        .update(workspaces)
+        .set({
+          name: wsNameChanged ? patch.workspace_name! : workspace.name,
+          active_repo: wsActiveRepo,
+          active_branch: wsActiveBranch,
+          updated_at: now,
+        })
+        .where(eq(workspaces.id, workspace.id))
+        .run();
+      if (wsNameChanged) workspace.name = patch.workspace_name!;
+      workspace.active_repo = wsActiveRepo;
+      workspace.active_branch = wsActiveBranch;
+      workspace.updated_at = now;
+    }
+
+    if (!existing) {
+      this._db
+        .insert(groupWorkspaces)
+        .values({
+          chat_id: chatId,
+          workspace_id: workspace.id,
+          created_at: now,
+          updated_at: now,
+        })
+        .run();
+      this.touchLastActive(workspace.id, now);
+      this._writeMetaFile(workspace);
+      return {
+        chat_id: chatId,
+        workspace_id: workspace.id,
+        workspace_name: workspace.name,
+        workspace_path: workspace.path,
+        active_repo: wsActiveRepo,
+        active_branch: wsActiveBranch,
+        created_at: now,
+        updated_at: now,
+      };
+    }
+
+    this._db
+      .update(groupWorkspaces)
+      .set({
+        workspace_id: workspace.id,
+        updated_at: now,
+      })
+      .where(eq(groupWorkspaces.chat_id, chatId))
+      .run();
+    this.touchLastActive(workspace.id, now);
+    this._writeMetaFile(workspace);
+    return {
+      ...existing,
+      workspace_id: workspace.id,
+      workspace_name: workspace.name,
+      workspace_path: workspace.path,
+      active_repo: wsActiveRepo,
+      active_branch: wsActiveBranch,
+      updated_at: now,
+    };
+  }
+
+  /**
+   * Remove the binding for a chat. No-op when absent. The workspace itself
+   * is kept — other groups may still be bound to it, and even when none are,
+   * we hold onto it so files in the directory aren't forgotten. Re-binding
+   * via `/bind <id>` remains possible after an unbind.
+   */
+  deleteBinding(chatId: string): boolean {
+    const existing = this.getBinding(chatId);
+    if (!existing) return false;
+    this._db
+      .delete(groupWorkspaces)
+      .where(eq(groupWorkspaces.chat_id, chatId))
+      .run();
+    const workspace = this.getWorkspace(existing.workspace_id);
+    if (workspace) this._writeMetaFile(workspace);
+    return true;
+  }
+
+  /**
+   * Resolve the cwd + envExtras pair a dispatch should use for this chat.
+   *
+   * - Binding present with active_repo → cwd = workspace_path,
+   *   DEV_ASSETS_PRIMARY_REPO/BRANCH in envExtras
+   * - Binding present without active_repo → cwd = workspace_path, no env hint
+   * - No binding (or no chatId) → cwd = default workspace, no env hint
+   *
+   * Guarantees cwd exists on disk.
+   */
+  resolve(chatId: string | null | undefined): WorkspaceResolution {
+    if (!chatId) {
+      return this._defaultResolution(null);
+    }
+    const binding = this.getBinding(chatId);
+    if (!binding) {
+      return this._defaultResolution(null);
+    }
+    if (!existsSync(binding.workspace_path)) {
+      mkdirSync(binding.workspace_path, { recursive: true });
+    }
+    this.touchLastActive(binding.workspace_id);
+    const envExtras: Record<string, string> = {};
+    if (binding.active_repo) {
+      envExtras.DEV_ASSETS_PRIMARY_REPO = binding.active_repo;
+      // Informational env — reflect the repo's actual HEAD, not the stored
+      // `active_branch` hint, so the agent sees what it will actually run on.
+      const head = readRepoHead(join(binding.workspace_path, binding.active_repo));
+      if (head) {
+        envExtras.DEV_ASSETS_PRIMARY_BRANCH = head;
+      }
+    }
+    return {
+      cwd: binding.workspace_path,
+      envExtras,
+      binding,
+    };
+  }
+
+  /**
+   * Bump `workspaces.last_active_at` for the given workspace. Cheap update —
+   * leaves `updated_at` alone so the two columns stay semantically distinct
+   * (`updated_at` = row mutated, `last_active_at` = workspace was used).
+   */
+  touchLastActive(workspaceId: string, ts: number = Date.now()): void {
+    this._db
+      .update(workspaces)
+      .set({ last_active_at: ts })
+      .where(eq(workspaces.id, workspaceId))
+      .run();
+  }
+
+  /**
+   * Fully remove a workspace: tasks → sessions → bindings → row → on-disk
+   * directory. The shared git-cache at `$AGENTARA_HOME/git-cache/` is left
+   * intact so other workspaces keep benefiting from it. Refuses to touch
+   * the reserved `_default` fallback directory.
+   */
+  deleteWorkspace(workspaceId: string): WorkspaceDeleteResult {
+    const workspace = this.getWorkspace(workspaceId);
+    if (!workspace) {
+      throw new WorkspaceNotFoundError(workspaceId);
+    }
+    if (workspace.path === config.paths.default_workspace) {
+      throw new WorkspaceProtectedError(workspaceId);
+    }
+
+    const sessionRows = this._db
+      .select({ id: sessions.id })
+      .from(sessions)
+      .where(
+        or(
+          eq(sessions.cwd, workspace.path),
+          like(sessions.cwd, `${workspace.path}/%`),
+        ),
+      )
+      .all();
+    const sessionIds = sessionRows.map((r) => r.id);
+
+    let removedTasks = 0;
+    if (sessionIds.length > 0) {
+      const taskRows = this._db
+        .select({ id: tasks.id })
+        .from(tasks)
+        .where(inArray(tasks.session_id, sessionIds))
+        .all();
+      removedTasks = taskRows.length;
+      if (removedTasks > 0) {
+        this._db.delete(tasks).where(inArray(tasks.session_id, sessionIds)).run();
+      }
+      this._db.delete(sessions).where(inArray(sessions.id, sessionIds)).run();
+    }
+
+    const bindingRows = this._db
+      .select({ chat_id: groupWorkspaces.chat_id })
+      .from(groupWorkspaces)
+      .where(eq(groupWorkspaces.workspace_id, workspaceId))
+      .all();
+    this._db
+      .delete(groupWorkspaces)
+      .where(eq(groupWorkspaces.workspace_id, workspaceId))
+      .run();
+    this._db.delete(workspaces).where(eq(workspaces.id, workspaceId)).run();
+
+    let removedDirectory = false;
+    try {
+      if (existsSync(workspace.path)) {
+        rmSync(workspace.path, { recursive: true, force: true });
+        removedDirectory = true;
+      }
+    } catch (err) {
+      this._logger.error(
+        { err, workspace_id: workspaceId, path: workspace.path },
+        "failed to remove workspace directory; db rows already gone",
+      );
+    }
+
+    const result: WorkspaceDeleteResult = {
+      workspace_id: workspaceId,
+      workspace_name: workspace.name,
+      workspace_path: workspace.path,
+      removed_bindings: bindingRows.length,
+      removed_sessions: sessionIds.length,
+      removed_tasks: removedTasks,
+      removed_directory: removedDirectory,
+    };
+    this._logger.info(result, "workspace deleted");
+    return result;
+  }
+
+  private _defaultResolution(
+    binding: GroupWorkspace | null,
+  ): WorkspaceResolution {
+    if (!existsSync(config.paths.default_workspace)) {
+      mkdirSync(config.paths.default_workspace, { recursive: true });
+    }
+    return {
+      cwd: config.paths.default_workspace,
+      envExtras: {},
+      binding,
+    };
+  }
+
+  private _resolveWorkspace(
+    chatId: string,
+    existing: GroupWorkspace | null,
+    patch: {
+      workspace_id?: string;
+      workspace_name?: string;
+      workspace_path?: string;
+    },
+    now: number,
+  ): Workspace {
+    if (patch.workspace_id) {
+      const workspace = this.getWorkspace(patch.workspace_id);
+      if (!workspace) {
+        throw new Error(`workspace id "${patch.workspace_id}" does not exist`);
+      }
+      this._ensureWorkspaceDir(workspace.path);
+      return workspace;
+    }
+
+    if (existing?.workspace_id) {
+      const workspace = this.getWorkspace(existing.workspace_id);
+      if (!workspace) {
+        throw new Error(
+          `workspace id "${existing.workspace_id}" referenced by chat "${chatId}" does not exist`,
+        );
+      }
+      this._ensureWorkspaceDir(workspace.path);
+      return workspace;
+    }
+
+    // Brand-new workspace: directory path is always derived from the stable
+    // id so `name` stays a pure display label. `patch.workspace_name` (or
+    // `workspace_path`'s basename as a last resort) only seeds the display
+    // name; it does not affect the on-disk directory.
+    const id = this._newWorkspaceId();
+    const workspacePath = config.paths.resolveWorkspacePathById(id);
+    const workspaceName =
+      patch.workspace_name ??
+      (patch.workspace_path ? _safeBasename(patch.workspace_path) : id);
+    this._ensureWorkspaceDir(workspacePath);
+    const workspace: Workspace = {
+      id,
+      name: workspaceName,
+      path: workspacePath,
+      active_repo: null,
+      active_branch: null,
+      created_at: now,
+      updated_at: now,
+      last_active_at: now,
+    };
+    this._db.insert(workspaces).values(workspace).run();
+    this._writeMetaFile(workspace);
+    return workspace;
+  }
+
+  private _ensureWorkspaceDir(workspacePath: string): void {
+    if (!existsSync(workspacePath)) {
+      mkdirSync(workspacePath, { recursive: true });
+      this._logger.info(`Created workspace: ${workspacePath}`);
+    }
+    this._linkGlobalAssets(workspacePath);
+  }
+
+  /**
+   * Symlink the shared instruction + memory surface from agentara home into
+   * every workspace root. Without this, Codex (whose `@import` resolver uses
+   * cwd as baseDir, and whose own auto-memory writes under `<cwd>/memory/`)
+   * ends up with a stale `<!-- file not found -->` AGENTS.md at the home
+   * level and a per-workspace memory island that never reaches the global
+   * SOUL/USER context. Symlinking is chosen over copying so writes on either
+   * side are seen by the other.
+   *
+   * Only `.claude/skills/` is shared from `.claude/` — the rest (runtime
+   * state, local settings, todos) stays per-workspace to avoid cross-session
+   * contention.
+   */
+  private _linkGlobalAssets(workspacePath: string): void {
+    // Never clobber agentara home itself; an in-home "workspace" would
+    // recurse onto its own files.
+    if (workspacePath === config.paths.home) return;
+    // Only manage workspaces under the managed workspaces root. If a user
+    // points at an arbitrary path, leave it alone.
+    if (!workspacePath.startsWith(config.paths.workspaces + sep)) return;
+
+    const linkSpecs: Array<{ src: string; dst: string }> = [
+      { src: join(config.paths.home, "CLAUDE.md"), dst: join(workspacePath, "CLAUDE.md") },
+      { src: config.paths.repos_md, dst: join(workspacePath, "REPOS.md") },
+      { src: config.paths.memory, dst: join(workspacePath, "memory") },
+      {
+        src: config.paths.skills,
+        dst: join(workspacePath, ".claude", "skills"),
+      },
+    ];
+
+    for (const { src, dst } of linkSpecs) {
+      if (!existsSync(src)) continue;
+      const parent = join(dst, "..");
+      if (!existsSync(parent)) {
+        try {
+          mkdirSync(parent, { recursive: true });
+        } catch (err) {
+          this._logger.warn({ err, parent }, "failed to create parent dir for symlink");
+          continue;
+        }
+      }
+      this._ensureSymlink(src, dst);
+    }
+  }
+
+  /**
+   * Idempotently ensure `dst` is a symlink pointing at `src`. If `dst` is
+   * already a symlink to the same target, no-op. If it's a symlink to a
+   * different target, replace it. If it's a real file or directory, move it
+   * aside to `<dst>.bak.<timestamp>` before creating the link, so we never
+   * silently destroy existing content.
+   */
+  private _ensureSymlink(src: string, dst: string): void {
+    try {
+      const st = lstatSync(dst, { throwIfNoEntry: false });
+      if (st) {
+        if (st.isSymbolicLink()) {
+          if (readlinkSync(dst) === src) return;
+          rmSync(dst);
+        } else {
+          const backup = `${dst}.bak.${Date.now()}`;
+          renameSync(dst, backup);
+          this._logger.info(
+            { dst, backup },
+            "backed up existing workspace asset before linking",
+          );
+        }
+      }
+      symlinkSync(src, dst);
+      this._logger.info({ src, dst }, "linked global asset into workspace");
+    } catch (err) {
+      this._logger.warn({ err, src, dst }, "failed to link global asset");
+    }
+  }
+
+  private _newWorkspaceId(): string {
+    return `ws_${uuid().replace(/-/g, "").slice(0, 12)}`;
+  }
+
+  private _mapJoinedBinding(row: {
+    group_workspaces: typeof groupWorkspaces.$inferSelect;
+    workspaces: typeof workspaces.$inferSelect;
+  }): GroupWorkspace {
+    return {
+      chat_id: row.group_workspaces.chat_id,
+      workspace_id: row.workspaces.id,
+      workspace_name: row.workspaces.name,
+      workspace_path: row.workspaces.path,
+      active_repo: row.workspaces.active_repo,
+      active_branch: row.workspaces.active_branch,
+      created_at: row.group_workspaces.created_at,
+      updated_at: row.group_workspaces.updated_at,
+    };
+  }
+
+  /**
+   * Boot-time fixup: move legacy workspace directories (named after chat_ids
+   * or user-picked slugs) to id-keyed paths. Idempotent; any row whose
+   * on-disk path already matches `workspaces/<id>/` is skipped. If a legacy
+   * directory exists on disk we `rename` it in place; if it's already gone
+   * we just create a fresh empty directory at the new path.
+   */
+  private _normalizeWorkspacePaths(): void {
+    const rows = this._db.select().from(workspaces).all();
+    const now = Date.now();
+    for (const row of rows) {
+      const desired = config.paths.resolveWorkspacePathById(row.id);
+      if (row.path === desired && existsSync(desired)) {
+        this._linkGlobalAssets(desired);
+        this._writeMetaFile(row);
+        continue;
+      }
+      if (row.path !== desired && existsSync(row.path) && !existsSync(desired)) {
+        try {
+          renameSync(row.path, desired);
+          this._logger.info(
+            { from: row.path, to: desired, workspace_id: row.id },
+            "normalized workspace path",
+          );
+        } catch (err) {
+          this._logger.error(
+            { err, from: row.path, to: desired, workspace_id: row.id },
+            "failed to normalize workspace path; leaving as-is",
+          );
+          continue;
+        }
+      } else if (!existsSync(desired)) {
+        this._ensureWorkspaceDir(desired);
+      }
+      this._db
+        .update(workspaces)
+        .set({ path: desired, updated_at: now })
+        .where(eq(workspaces.id, row.id))
+        .run();
+      this._writeMetaFile({ ...row, path: desired, updated_at: now });
+    }
+  }
+
+  /**
+   * Write / overwrite the `AGENTARA.md` info file at the workspace root.
+   * This is a human-readable summary of the workspace: stable id, display
+   * name, on-disk path, bound chats, and active repo/branch. Safe to
+   * regenerate on every mutation; the file is marked as auto-generated.
+   */
+  private _writeMetaFile(workspace: Workspace): void {
+    try {
+      const bindings = this._db
+        .select({ chat_id: groupWorkspaces.chat_id })
+        .from(groupWorkspaces)
+        .where(eq(groupWorkspaces.workspace_id, workspace.id))
+        .all();
+      const chatLines =
+        bindings.length === 0
+          ? "- _(none — run `/bind` in a chat to attach.)_"
+          : bindings.map((b) => `- \`${b.chat_id}\``).join("\n");
+      const active = workspace.active_repo
+        ? `\`${workspace.active_repo}${
+            workspace.active_branch ? " " + workspace.active_branch : ""
+          }\``
+        : "_(unset)_";
+      const lines = [
+        `# Workspace: ${workspace.name}`,
+        "",
+        `- **ID**: \`${workspace.id}\``,
+        `- **Path**: \`${workspace.path}\``,
+        `- **Active repo**: ${active}`,
+        `- **Created**: ${_formatTs(workspace.created_at)}`,
+        `- **Updated**: ${_formatTs(workspace.updated_at)}`,
+        "",
+        "## Bound chats",
+        "",
+        chatLines,
+        "",
+        "<!-- Auto-generated by agentara. Edit via `/setup` in a bound chat. -->",
+        "",
+      ];
+      if (!existsSync(workspace.path)) {
+        mkdirSync(workspace.path, { recursive: true });
+      }
+      writeFileSync(join(workspace.path, META_FILE_NAME), lines.join("\n"));
+    } catch (err) {
+      this._logger.warn(
+        { err, workspace_id: workspace.id },
+        "failed to write workspace meta file",
+      );
+    }
+  }
+}
+
+/**
+ * Breakdown of what {@link GroupWorkspaceStore.deleteWorkspace} actually
+ * removed. The card uses these counts in the result summary so users see
+ * exactly how much state went away.
+ */
+export interface WorkspaceDeleteResult {
+  workspace_id: string;
+  workspace_name: string;
+  workspace_path: string;
+  removed_bindings: number;
+  removed_sessions: number;
+  removed_tasks: number;
+  removed_directory: boolean;
+}
+
+/** Thrown when the caller asks to delete a workspace id that doesn't exist. */
+export class WorkspaceNotFoundError extends Error {
+  constructor(readonly workspace_id: string) {
+    super(`workspace id "${workspace_id}" does not exist`);
+    this.name = "WorkspaceNotFoundError";
+  }
+}
+
+/** Thrown when the caller asks to delete the reserved default workspace. */
+export class WorkspaceProtectedError extends Error {
+  constructor(readonly workspace_id: string) {
+    super(
+      `workspace "${workspace_id}" is protected (default fallback) and cannot be deleted`,
+    );
+    this.name = "WorkspaceProtectedError";
+  }
+}
+
+function _safeBasename(p: string): string {
+  const trimmed = p.replace(/[\\/]+$/, "");
+  const idx = Math.max(
+    trimmed.lastIndexOf("/"),
+    trimmed.lastIndexOf("\\"),
+  );
+  return idx >= 0 ? trimmed.slice(idx + 1) : trimmed;
+}
+
+function _formatTs(ms: number): string {
+  return dayjs(ms).format("YYYY-MM-DD HH:mm:ss");
+}
diff --git a/src/plugins/_country-check.ts b/src/plugins/_country-check.ts
new file mode 100644
index 0000000..0b88e5d
--- /dev/null
+++ b/src/plugins/_country-check.ts
@@ -0,0 +1,119 @@
+import { createLogger } from "@/shared";
+
+const _logger = createLogger("country-check");
+
+/**
+ * Endpoints that return the caller's country as a 2-letter ISO code. Both
+ * probes fire in parallel and the first successful answer wins — either
+ * endpoint being slow or offline no longer stalls the gate.
+ *
+ * `ipapi.co` was dropped: it rate-limits aggressively from shared egress
+ * IPs, which was the main source of the 2s timeout we'd then serialize on.
+ *
+ * Mirrors the zshrc preamble so agentara spawns fire under the same guard:
+ * if the outbound proxy isn't landing somewhere expected, we bail loudly
+ * before the agent starts billing tokens.
+ */
+const COUNTRY_PROBES = [
+  { url: "https://ifconfig.co/country-iso", kind: "text" as const },
+  { url: "https://api.country.is/", kind: "country_is_json" as const },
+];
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/**
+ * Race every IP-geolocation probe in parallel and return the first ISO
+ * country code that comes back. Resolves to `null` only when every probe
+ * fails (network down, all providers rate-limited, etc.) — callers
+ * distinguish that from a successful detection with `country !== "US"`.
+ */
+export async function detectCountry(options?: {
+  /** Proxy URL (e.g. `http://127.0.0.1:7897`). Skipped when undefined. */
+  proxy?: string;
+  /** Per-request timeout. Defaults to 5s, matching the zshrc curl max-time. */
+  timeoutMs?: number;
+}): Promise<string | null> {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const proxy = options?.proxy;
+
+  const probes = COUNTRY_PROBES.map((probe) =>
+    _runProbe(probe, { proxy, timeoutMs }),
+  );
+  return _firstNonNull(probes);
+}
+
+async function _runProbe(
+  probe: (typeof COUNTRY_PROBES)[number],
+  options: { proxy?: string; timeoutMs: number },
+): Promise<string | null> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    // Bun's `fetch` accepts a `proxy` option natively — no undici
+    // ProxyAgent setup needed. The signal handles the timeout.
+    const res = await fetch(probe.url, {
+      signal: controller.signal,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun's proxy option isn't in lib.dom.fetch yet
+      ...(options.proxy ? ({ proxy: options.proxy } as any) : {}),
+    });
+    if (!res.ok) return null;
+    const text = await res.text();
+    const parsed = _parseCountry(text, probe.kind);
+    if (parsed) {
+      _logger.debug({ probe: probe.url, country: parsed }, "country detected");
+    }
+    return parsed;
+  } catch (err) {
+    _logger.debug({ err, probe: probe.url }, "country probe failed");
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Resolve with the first non-null value produced by any of the input
+ * promises. Resolves to `null` when every promise yields null/rejects —
+ * rejections are treated as failed probes, not fatal errors.
+ */
+function _firstNonNull<T>(
+  promises: Array<Promise<T | null>>,
+): Promise<T | null> {
+  return new Promise((resolve) => {
+    if (promises.length === 0) {
+      resolve(null);
+      return;
+    }
+    let pending = promises.length;
+    let settled = false;
+    const finish = (value: T | null) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    for (const p of promises) {
+      p.then(
+        (v) => {
+          if (v !== null) finish(v);
+          else if (--pending === 0) finish(null);
+        },
+        () => {
+          if (--pending === 0) finish(null);
+        },
+      );
+    }
+  });
+}
+
+function _parseCountry(
+  body: string,
+  kind: "text" | "country_is_json",
+): string | null {
+  if (kind === "country_is_json") {
+    const match = body.match(/"country"\s*:\s*"([A-Z]{2})"/);
+    return match ? match[1]! : null;
+  }
+  // Plain text: strip whitespace, take first 2 uppercase chars.
+  const head = body.trim().slice(0, 2).toUpperCase();
+  return /^[A-Z]{2}$/.test(head) ? head : null;
+}
diff --git a/src/plugins/claude-gated.ts b/src/plugins/claude-gated.ts
new file mode 100644
index 0000000..d7b3c0b
--- /dev/null
+++ b/src/plugins/claude-gated.ts
@@ -0,0 +1,145 @@
+import { ClaudeAgentRunner } from "@/community/anthropic";
+import { registerRunner } from "@/kernel/agents";
+import {
+  config,
+  createLogger,
+  type AgentRunOptions,
+  type AgentRunner,
+  type AssistantMessage,
+  type SystemMessage,
+  type ToolMessage,
+  type UserMessage,
+} from "@/shared";
+
+const _logger = createLogger("claude-gated");
+const CLASH_CONTROLLER_SOCKET = "/tmp/verge/verge-mihomo.sock";
+const HTTP_PROXY_CHECK_URL = "http://www.gstatic.com/generate_204";
+const PROXY_READY_TIMEOUT_MS = 5000;
+
+/**
+ * Wraps {@link ClaudeAgentRunner} with the safety preamble the user runs
+ * in zshrc before invoking the real `claude` CLI:
+ *
+ *   1. Resolve a proxy URL (from `agents.env.HTTPS_PROXY` / `HTTP_PROXY`)
+ *      and use it both for the local proxy readiness check and for the
+ *      delegated spawn's env.
+ *   2. Check whether Clash Verge/Mihomo TUN is enabled, or whether the
+ *      configured local HTTP proxy can fetch a lightweight connectivity URL.
+ *      Abort only when both are unavailable.
+ *   3. Delegate to the built-in Claude runner, carrying the proxy through
+ *      via `envExtras` so the inner spawn actually goes through it, and
+ *      force `--dangerously-skip-permissions` on — this wrapper exists for
+ *      the unattended robot flow where the agent runs inside a controlled
+ *      workspace, so per-tool approvals just stall the pipeline.
+ *
+ * Enable by setting `agents.default.type: "claude-gated"` in `config.yaml`.
+ */
+class ClaudeGatedRunner implements AgentRunner {
+  readonly type = "claude-gated";
+  private readonly _inner = new ClaudeAgentRunner();
+
+  async *stream(
+    message: UserMessage,
+    options: AgentRunOptions,
+  ): AsyncIterableIterator<SystemMessage | AssistantMessage | ToolMessage> {
+    const proxy = _resolveProxy();
+
+    const readyVia = await _clashProxyReady(proxy);
+    if (readyVia === null) {
+      throw new Error(
+        "Clash TUN 未开启，HTTP 代理也不可用，已拦截 Claude 启动（claude-gated）。",
+      );
+    }
+    _logger.info({ readyVia }, "clash proxy gate passed");
+
+    const mergedOptions: AgentRunOptions = {
+      ...options,
+      dangerouslySkipPermissions: true,
+      ...(proxy
+        ? {
+            envExtras: {
+              ...(options.envExtras ?? {}),
+              HTTP_PROXY: proxy,
+              HTTPS_PROXY: proxy,
+            },
+          }
+        : {}),
+    };
+
+    yield* this._inner.stream(message, mergedOptions);
+  }
+}
+
+async function _clashProxyReady(proxy: string | undefined): Promise<string | null> {
+  if (await _isClashTunEnabled()) return "tun";
+  if (proxy && (await _isHttpProxyReady(proxy))) return "http-proxy";
+  return null;
+}
+
+async function _isClashTunEnabled(): Promise<boolean> {
+  try {
+    const result = await _runCurl(
+      [
+        "-fsS",
+        "--unix-socket",
+        CLASH_CONTROLLER_SOCKET,
+        "http://localhost/configs",
+      ],
+      PROXY_READY_TIMEOUT_MS,
+    );
+    if (result.exitCode !== 0) return false;
+    const configs = JSON.parse(result.stdout) as {
+      tun?: { enable?: unknown };
+    };
+    return configs.tun?.enable === true;
+  } catch (err) {
+    _logger.debug({ err }, "clash tun readiness check failed");
+    return false;
+  }
+}
+
+async function _isHttpProxyReady(proxy: string): Promise<boolean> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), PROXY_READY_TIMEOUT_MS);
+  try {
+    const res = await fetch(HTTP_PROXY_CHECK_URL, {
+      signal: controller.signal,
+      proxy,
+    } as RequestInit & { proxy: string });
+    return res.status === 204 || res.ok;
+  } catch (err) {
+    _logger.debug({ err, proxy }, "http proxy readiness check failed");
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function _runCurl(
+  args: string[],
+  timeoutMs: number,
+): Promise<{ exitCode: number; stdout: string }> {
+  const proc = Bun.spawn(["curl", ...args], {
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  const timer = setTimeout(() => proc.kill(), timeoutMs);
+  try {
+    const [stdout, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      proc.exited,
+    ]);
+    return { exitCode, stdout };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function _resolveProxy(): string | undefined {
+  const envMap = config.agents.env ?? {};
+  return (
+    envMap.HTTPS_PROXY ?? envMap.HTTP_PROXY ?? envMap.https_proxy ?? envMap.http_proxy
+  );
+}
+
+registerRunner("claude-gated", () => new ClaudeGatedRunner());
diff --git a/src/plugins/codex-yolo.ts b/src/plugins/codex-yolo.ts
new file mode 100644
index 0000000..5604b84
--- /dev/null
+++ b/src/plugins/codex-yolo.ts
@@ -0,0 +1,46 @@
+import { CodexAgentRunner } from "@/community/openai";
+import { registerRunner } from "@/kernel/agents";
+import {
+  type AgentRunOptions,
+  type AgentRunner,
+  type AssistantMessage,
+  type SystemMessage,
+  type ToolMessage,
+  type UserMessage,
+} from "@/shared";
+
+const YOLO_PROXY = "http://127.0.0.1:7897";
+
+/**
+ * Codex runner variant matching the local shell helper:
+ *
+ *   HTTP_PROXY=http://127.0.0.1:7897
+ *   HTTPS_PROXY=http://127.0.0.1:7897
+ *   codex --search exec --dangerously-bypass-approvals-and-sandbox ...
+ *
+ * The base Codex runner already owns `exec`, JSON streaming, resume handling,
+ * and the dangerous bypass flag, so this plugin only injects the fixed proxy
+ * and the additional top-level `--search` CLI flag.
+ */
+class CodexYoloRunner implements AgentRunner {
+  readonly type = "codex-yolo";
+  private readonly _inner = new CodexAgentRunner({
+    extraGlobalArgs: ["--search"],
+  });
+
+  async *stream(
+    message: UserMessage,
+    options: AgentRunOptions,
+  ): AsyncIterableIterator<SystemMessage | AssistantMessage | ToolMessage> {
+    yield* this._inner.stream(message, {
+      ...options,
+      envExtras: {
+        ...(options.envExtras ?? {}),
+        HTTP_PROXY: YOLO_PROXY,
+        HTTPS_PROXY: YOLO_PROXY,
+      },
+    });
+  }
+}
+
+registerRunner("codex-yolo", () => new CodexYoloRunner());
diff --git a/src/plugins/index.ts b/src/plugins/index.ts
new file mode 100644
index 0000000..adff1c8
--- /dev/null
+++ b/src/plugins/index.ts
@@ -0,0 +1,12 @@
+/**
+ * Plugin barrel — importing this module side-effects registers every
+ * plugin under `src/plugins/*` with the agent runner registry. Add new
+ * plugins by creating a module that calls `registerRunner(...)` at
+ * top-level and appending it to this barrel.
+ *
+ * The kernel imports this once at startup (see `kernel.ts`), so by the
+ * time the first session dispatches, every plugin runner is resolvable
+ * via `agents.default.type` in config.yaml.
+ */
+import "./claude-gated";
+import "./codex-yolo";
diff --git a/src/server/routes/index.ts b/src/server/routes/index.ts
index 996a602..e5b8730 100644
--- a/src/server/routes/index.ts
+++ b/src/server/routes/index.ts
@@ -2,6 +2,7 @@ export { cronjobsRoutes } from "./cronjobs";
 export { handoffRoutes } from "./handoff";
 export { healthRoutes } from "./health";
 export { memoryRoutes } from "./memory";
+export { permissionRoutes } from "./permission";
 export { sessionRoutes } from "./sessions";
 export { skillsRoutes } from "./skills";
 export { taskRoutes } from "./tasks";
diff --git a/src/server/routes/permission.ts b/src/server/routes/permission.ts
new file mode 100644
index 0000000..9d64278
--- /dev/null
+++ b/src/server/routes/permission.ts
@@ -0,0 +1,63 @@
+import { zValidator } from "@hono/zod-validator";
+import { Hono } from "hono";
+import { z } from "zod";
+
+import { kernel } from "@/kernel";
+import { createLogger } from "@/shared";
+
+const _logger = createLogger("permission-routes");
+
+/**
+ * Request body posted by the MCP stdio subprocess when Claude Code
+ * invokes the `approve_tool_use` tool. The subprocess forwards the
+ * Claude-side payload plus the per-session context that was baked into
+ * its spawn env, so the kernel can route the card to the right chat.
+ */
+const PermissionRequestBody = z.object({
+  session_id: z.string(),
+  channel_id: z.string(),
+  chat_id: z.string(),
+  initiator_open_id: z.string(),
+  reply_to_message_id: z.string().optional(),
+  tool_name: z.string(),
+  tool_input: z.record(z.string(), z.unknown()),
+});
+
+/**
+ * Internal-only endpoint the MCP permission subprocess long-polls
+ * against. Not mounted under `/api` because it isn't part of the
+ * public surface; bearer-token auth against {@link PermissionFlow.apiToken}
+ * is the only gate.
+ */
+export const permissionRoutes = new Hono().post(
+  "/request",
+  zValidator("json", PermissionRequestBody),
+  async (c) => {
+    const authz = c.req.header("Authorization") ?? "";
+    const token = authz.startsWith("Bearer ") ? authz.slice(7) : "";
+    if (!kernel.permissionFlow.verifyToken(token)) {
+      _logger.warn("unauthorized permission request");
+      return c.json({ error: "unauthorized" }, 401);
+    }
+    const body = c.req.valid("json");
+    const decision = await kernel.permissionFlow.request({
+      session_id: body.session_id,
+      channel_id: body.channel_id,
+      chat_id: body.chat_id,
+      initiator_open_id: body.initiator_open_id,
+      reply_to_message_id: body.reply_to_message_id,
+      tool_name: body.tool_name,
+      tool_input: body.tool_input,
+    });
+    if (decision.behavior === "allow") {
+      return c.json({
+        behavior: "allow",
+        updatedInput: decision.updated_input ?? body.tool_input,
+      });
+    }
+    return c.json({
+      behavior: "deny",
+      message: decision.message ?? "Permission denied",
+    });
+  },
+);
diff --git a/src/server/routes/usage.ts b/src/server/routes/usage.ts
index e07ab5f..7f5194f 100644
--- a/src/server/routes/usage.ts
+++ b/src/server/routes/usage.ts
@@ -1,79 +1,10 @@
 import { Hono } from "hono";
 
+import { queryClaudeUsage } from "@/community/anthropic";
 import { createLogger } from "@/shared";
 
 const logger = createLogger("usage");
 
-/**
- * Reads Claude Code credentials from macOS Keychain via `security find-generic-password`.
- * Returns the stored value (a JSON string) parsed as an object.
- */
-async function getClaudeCredentials() {
-  const proc = Bun.spawn(
-    [
-      "security",
-      "find-generic-password",
-      "-s",
-      "Claude Code-credentials",
-      "-w",
-    ],
-    { stdout: "pipe", stderr: "pipe" },
-  );
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  const exit = await proc.exited;
-  if (exit !== 0) {
-    logger.warn({ exit, stderr }, "security find-generic-password failed");
-    throw new Error(stderr || `security command exited with code ${exit}`);
-  }
-  const trimmed = stdout.trim();
-  if (!trimmed) {
-    throw new Error("empty credentials from keychain");
-  }
-  return JSON.parse(trimmed) as {
-    claudeAiOauth: {
-      accessToken: string;
-      refreshToken: string;
-      expiresAt: number;
-    };
-  };
-}
-
-async function queryClaudeUsage() {
-  const credentials = await getClaudeCredentials();
-  const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
-    headers: new Headers({
-      "anthropic-beta": "oauth-2025-04-20",
-      Authorization: `Bearer ${credentials.claudeAiOauth.accessToken}`,
-    }),
-  });
-  return (await response.json()) as {
-    five_hour: {
-      utilization: number;
-      resets_at: string | null;
-    };
-    seven_day: {
-      utilization: number;
-      resets_at: string;
-    };
-    extra_usage:
-      | {
-          is_enabled: true;
-          monthly_limit: number;
-          used_credits: number;
-          utilization: number;
-        }
-      | {
-          is_enabled: false;
-          monthly_limit: null;
-          used_credits: null;
-          utilization: null;
-        };
-  };
-}
-
 /**
  * Usage route group. Serves Claude usage / credentials data.
  */
diff --git a/src/server/server.ts b/src/server/server.ts
index ba6cbf9..f5adf36 100644
--- a/src/server/server.ts
+++ b/src/server/server.ts
@@ -14,6 +14,7 @@ import {
   handoffRoutes,
   healthRoutes,
   memoryRoutes,
+  permissionRoutes,
   sessionRoutes,
   skillsRoutes,
   taskRoutes,
@@ -41,6 +42,10 @@ function createApp() {
       .route("/api/skills", skillsRoutes)
       .route("/api/tasks", taskRoutes)
       .route("/api/usage", usageRoutes)
+      // Internal-only route used by the Claude permission MCP subprocess.
+      // Auth is bearer-token against a rotating in-memory secret (see
+      // PermissionFlow.apiToken). Keep off `/api` so it doesn't get CORS.
+      .route("/internal/permission", permissionRoutes)
   );
 }
 
diff --git a/src/shared/agents/agent-runner.ts b/src/shared/agents/agent-runner.ts
index fafe1ca..02b4571 100644
--- a/src/shared/agents/agent-runner.ts
+++ b/src/shared/agents/agent-runner.ts
@@ -26,11 +26,25 @@ export const AgentRunOptions = z.object({
    */
   runnerSessionId: z.string().optional(),
 
+  /**
+   * Extra environment variables merged into the runner's spawn env. Used to
+   * thread per-group hints (e.g. `DEV_ASSETS_PRIMARY_REPO`) into Claude/Codex
+   * CLI invocations without touching the caller's process env.
+   */
+  envExtras: z.record(z.string(), z.string()).optional(),
+
   /**
    * Abort signal for cancelling the running task.
    * When aborted, the agent runner should kill any spawned subprocesses.
    */
   signal: z.instanceof(AbortSignal).optional(),
+
+  /**
+   * When `true`, the Claude CLI is spawned with
+   * `--dangerously-skip-permissions` so every tool call is auto-approved.
+   * Off by default — only the gated/robot-facing wrappers should set it.
+   */
+  dangerouslySkipPermissions: z.boolean().optional(),
 });
 export interface AgentRunOptions extends z.infer<typeof AgentRunOptions> {}
 
diff --git a/src/shared/config/index.ts b/src/shared/config/index.ts
index 6bba5a2..76a07da 100644
--- a/src/shared/config/index.ts
+++ b/src/shared/config/index.ts
@@ -12,10 +12,14 @@ export type {
   AppConfig,
   ChannelConfig,
   ChannelParams,
+  CodexConfig,
   MessagingConfig,
+  SettingConfig,
   TaskingConfig,
 } from "./schema";
 
+export { loadPredefinedRepos, PredefinedRepo } from "./predefined-repos";
+
 /**
  * Combined configuration interface including both YAML-loaded app config and paths.
  */
@@ -88,5 +92,15 @@ export const config = {
     }
     return _appConfig.messaging;
   },
+  get setting() {
+    if (!_appConfig) {
+      // Fall back to the schema default ({ admin_open_ids: [] }) when the
+      // YAML hasn't been loaded yet (e.g. in early boot / unit tests). This
+      // keeps the gate permissive instead of throwing — the gate is a
+      // safety check, not load-bearing for boot.
+      return { admin_open_ids: [] as string[] };
+    }
+    return _appConfig.setting;
+  },
   paths,
 };
diff --git a/src/shared/config/paths.ts b/src/shared/config/paths.ts
index 84d9f86..1f1c57e 100644
--- a/src/shared/config/paths.ts
+++ b/src/shared/config/paths.ts
@@ -11,6 +11,8 @@ export function resolveSessionFilePath(session_id: string) {
   return join(sessions, `${session_id}.jsonl`);
 }
 
+export const repos_md = join(home, "REPOS.md");
+
 export const memory = join(home, "memory");
 export const logs = join(memory, "logs");
 export function resolveDailyLogFilePath(date: Date) {
@@ -18,11 +20,59 @@ export function resolveDailyLogFilePath(date: Date) {
   return join(logs, `${dateString}.md`);
 }
 
+/**
+ * Runtime log files written alongside stdout by pino. One file per day,
+ * `YYYY-MM-DD.log`. Conceptually distinct from `memory/logs/` (which stores
+ * structured agent diaries); these are operational logs for debugging the
+ * agentara process itself.
+ */
+export const runtime_logs = join(home, "runtime-logs");
+export function resolveRuntimeLogFilePath(date: Date) {
+  const dateString = dayjs(date).format("YYYY-MM-DD");
+  return join(runtime_logs, `${dateString}.log`);
+}
+
 export const workspace = join(home, "workspace");
 export const projects = join(workspace, "projects");
 export const uploads = join(workspace, "uploads");
 export const outputs = join(workspace, "outputs");
 
+/**
+ * Workspace root container: `$AGENTARA_HOME/workspaces/<workspace_id>/`.
+ * `_default/` inside it is the fallback workspace for unbound groups.
+ *
+ * Each workspace directory is keyed by its stable `ws_xxx` id so the
+ * human-readable `name` stays a pure display label — it can be renamed
+ * at any time without moving files. `resolveWorkspacePathByName` stays
+ * for diagnostics; `resolveGroupWorkspacePath` is kept only for legacy
+ * bindings created before id-based paths existed and is normalized away
+ * at boot.
+ */
+export const workspaces = join(home, "workspaces");
+export const default_workspace = join(workspaces, "_default");
+
+/**
+ * Object-only cache of bare git mirrors, one per predefined repo name.
+ * Used as the `--reference` source when cloning repos into workspaces so
+ * object downloads are paid at most once across all workspaces. Never
+ * used as a worktree or user-facing workspace — agentara maintains these
+ * mirrors exclusively (clone, fetch). Losing this directory degrades to
+ * "every clone is a fresh full clone" — still correct, just slower.
+ */
+export const git_cache = join(home, "git-cache");
+export function resolveGitCachePath(repo_name: string) {
+  return join(git_cache, `${repo_name}.git`);
+}
+export function resolveWorkspacePathById(workspace_id: string) {
+  return join(workspaces, workspace_id);
+}
+export function resolveWorkspacePathByName(name: string) {
+  return join(workspaces, name);
+}
+export function resolveGroupWorkspacePath(chat_id: string) {
+  return join(workspaces, chat_id);
+}
+
 export const data = join(home, "data");
 export function resolveDataFilePath(filename: string) {
   return join(data, filename);
@@ -32,3 +82,13 @@ export const claude_home = join(home, ".claude");
 export const skills = join(claude_home, "skills");
 
 export const agents_home = join(home, ".agents");
+
+/**
+ * Isolated `CODEX_HOME` for spawned Codex CLI processes.  Keeps
+ * Codex's base config, sessions, state, and skills separate from
+ * the host's `~/.codex/`.  Boot-loader seeds an `auth.json` symlink
+ * so the OAuth login is shared bi-directionally.  Activated only
+ * when `agents.codex.isolate_host_env` is `true`.
+ */
+export const codex_home = join(home, ".codex");
+export const host_codex_home = join(user_home, ".codex");
diff --git a/src/shared/config/predefined-repos.ts b/src/shared/config/predefined-repos.ts
new file mode 100644
index 0000000..efddfbf
--- /dev/null
+++ b/src/shared/config/predefined-repos.ts
@@ -0,0 +1,121 @@
+import { existsSync, readFileSync } from "node:fs";
+
+import { z } from "zod";
+
+import * as paths from "./paths";
+
+/**
+ * A predefined repository surfaced by the `/setup` command. The catalog is
+ * maintained as Markdown in `$AGENTARA_HOME/REPOS.md` rather than YAML so
+ * the same file can double as free-form context that agents read via
+ * CLAUDE.md's `@REPOS.md` import — and update in place as they learn more
+ * about each repo.
+ *
+ * `description` is a short one-liner shown on the `/setup` card next to
+ * the repo name. Prefer an explicit `- description: <one-liner>` bullet
+ * in the section so the card copy stays short; if absent we fall back to
+ * the first prose line for backward compatibility. The rest of the section
+ * body is free-form agent context, not used by the card renderer.
+ */
+export const PredefinedRepo = z.object({
+  name: z.string(),
+  description: z.string().default(""),
+  git_url: z.string(),
+});
+export interface PredefinedRepo extends z.infer<typeof PredefinedRepo> {}
+
+/**
+ * Read and parse `$AGENTARA_HOME/REPOS.md`. Returns an empty list when the
+ * file does not exist or contains no valid repo sections. Called on demand
+ * by `/setup` (not cached) so operators can edit the file and see the
+ * change reflected on the next command without restarting the kernel.
+ */
+export function loadPredefinedRepos(): PredefinedRepo[] {
+  if (!existsSync(paths.repos_md)) return [];
+  const raw = readFileSync(paths.repos_md, "utf-8");
+  return _parseReposMarkdown(raw);
+}
+
+interface _PartialRepo {
+  name: string;
+  git_url?: string;
+  description?: string;
+}
+
+/**
+ * Parse a `REPOS.md`-style document. Each `## <name>` begins a repo;
+ * the first `- git_url: <url>` bullet fills `git_url`; a
+ * `- description: <one-liner>` bullet, if present, fills `description`.
+ * If that bullet is missing, we fall back to the first non-bullet,
+ * non-heading, non-comment prose line so older files still render.
+ */
+function _parseReposMarkdown(markdown: string): PredefinedRepo[] {
+  const lines = markdown.split(/\r?\n/);
+  const out: PredefinedRepo[] = [];
+  let current: _PartialRepo | null = null;
+  let proseFallbackCaptured = false;
+  let hasExplicitDescription = false;
+  let inHtmlComment = false;
+
+  const flush = () => {
+    if (current && current.name && current.git_url) {
+      const parsed = PredefinedRepo.safeParse({
+        name: current.name,
+        git_url: current.git_url,
+        description: current.description ?? "",
+      });
+      if (parsed.success) out.push(parsed.data);
+    }
+  };
+
+  for (const line of lines) {
+    if (inHtmlComment) {
+      if (line.includes("-->")) inHtmlComment = false;
+      continue;
+    }
+    if (line.trim().startsWith("<!--") && !line.includes("-->")) {
+      inHtmlComment = true;
+      continue;
+    }
+
+    const h2 = /^##\s+(.+?)\s*$/.exec(line);
+    if (h2) {
+      flush();
+      current = { name: h2[1]!.trim() };
+      proseFallbackCaptured = false;
+      hasExplicitDescription = false;
+      continue;
+    }
+    if (!current) continue;
+
+    const gitUrl = /^\s*-\s*git_url\s*:\s*(\S.*?)\s*$/.exec(line);
+    if (gitUrl) {
+      current.git_url = gitUrl[1];
+      continue;
+    }
+
+    const desc = /^\s*-\s*description\s*:\s*(\S.*?)\s*$/.exec(line);
+    if (desc) {
+      current.description = desc[1];
+      hasExplicitDescription = true;
+      continue;
+    }
+
+    if (!hasExplicitDescription && !proseFallbackCaptured) {
+      const trimmed = line.trim();
+      if (
+        trimmed &&
+        !trimmed.startsWith("-") &&
+        !trimmed.startsWith("#") &&
+        !trimmed.startsWith("<!--") &&
+        !trimmed.startsWith(">")
+      ) {
+        current.description = trimmed;
+        proseFallbackCaptured = true;
+      }
+    }
+  }
+  flush();
+
+  return out;
+}
diff --git a/src/shared/config/schema.ts b/src/shared/config/schema.ts
index 2b91983..c1296ff 100644
--- a/src/shared/config/schema.ts
+++ b/src/shared/config/schema.ts
@@ -2,18 +2,48 @@ import { z } from "zod";
 
 /**
  * Configuration for a single agent.
+ *
+ * `model` is optional on purpose — when unset, the runner skips the
+ * `--model` CLI flag entirely so the underlying tool (Claude Code, Codex)
+ * picks its own default. This sidesteps the "one model key for two CLIs"
+ * problem where e.g. `claude-sonnet-4-6` is nonsense to Codex.
  */
 export const AgentConfig = z.object({
   type: z.string(),
-  model: z.string().default("claude-sonnet-4-6"),
+  model: z.string().optional(),
 });
 export interface AgentConfig extends z.infer<typeof AgentConfig> {}
 
+/**
+ * Codex CLI-specific runtime options.
+ */
+export const CodexConfig = z.object({
+  /**
+   * When `true`, agentara points spawned Codex at its own
+   * `CODEX_HOME` so config / sessions / state / skills stay
+   * separate from the host's `~/.codex/`.  Host `~/.codex/hooks.json`
+   * is still loaded by Codex via its cwd-ancestor climb — move
+   * that file out of `~/.codex/` yourself if you need it to skip
+   * agentara workspaces.  Default `false` — agentara reuses the
+   * host setup.
+   */
+  isolate_host_env: z.boolean().default(false),
+});
+export interface CodexConfig extends z.infer<typeof CodexConfig> {}
+
 /**
  * Configuration for all agents.
+ *
+ * `env` is merged into every agent spawn's environment — both Claude and
+ * Codex. Use it to inject static variables the host shell wouldn't provide
+ * (proxy settings, custom certs, feature flags). It sits between `Bun.env`
+ * and per-dispatch `envExtras` in the precedence chain, so workspace-level
+ * overrides still win and the host env stays the baseline.
  */
 export const AgentsConfig = z.object({
   default: AgentConfig,
+  codex: CodexConfig.default({ isolate_host_env: false }),
+  env: z.record(z.string(), z.string()).default({}),
 });
 export interface AgentsConfig extends z.infer<typeof AgentsConfig> {}
 
@@ -26,9 +56,26 @@ export const TaskingConfig = z.object({
 export interface TaskingConfig extends z.infer<typeof TaskingConfig> {}
 
 /**
- * Key-value parameters for a messaging channel.
+ * Key-value parameters for a messaging channel. Accepts string, boolean,
+ * number, or an array of the same in YAML (e.g. `require_mention: true`,
+ * `allowed_user_ids: [ou_aaa, ou_bbb]`) and normalizes to strings so downstream
+ * consumers always work with a uniform `Record<string, string>` shape. Arrays
+ * are joined with commas — safe for identifiers that never contain commas
+ * (open_id, union_id, etc.).
  */
-export const ChannelParams = z.record(z.string(), z.string());
+export const ChannelParams = z.record(
+  z.string(),
+  z
+    .union([
+      z.string(),
+      z.boolean(),
+      z.number(),
+      z.array(z.union([z.string(), z.boolean(), z.number()])),
+    ])
+    .transform((v) =>
+      Array.isArray(v) ? v.map(String).join(",") : String(v),
+    ),
+);
 export type ChannelParams = z.infer<typeof ChannelParams>;
 
 /**
@@ -52,8 +99,26 @@ export const MessagingConfig = z.object({
 });
 export interface MessagingConfig extends z.infer<typeof MessagingConfig> {}
 
+/**
+ * Configuration for the `/setting` admin panel.
+ *
+ * `admin_open_ids` is an explicit allowlist for who may open the panel and
+ * interact with its callback buttons. Empty (the default) means "no
+ * restriction" — backward compatible with existing deployments where the
+ * channel-level whitelist already gates inbound traffic. Non-empty switches
+ * to strict mode: only listed open_ids may run `/setting` and click on its
+ * cards; everyone else gets a plain-text rejection.
+ */
+export const SettingConfig = z.object({
+  admin_open_ids: z.array(z.string()).default([]),
+});
+export interface SettingConfig extends z.infer<typeof SettingConfig> {}
+
 /**
  * Top-level application configuration loaded from config.yaml.
+ *
+ * The `/setup` catalog lives in `$AGENTARA_HOME/REPOS.md`, not here — see
+ * `./predefined-repos.ts`.
  */
 export const AppConfig = z.object({
   /** IANA timezone identifier, e.g. `"Asia/Shanghai"`. Defaults to the system timezone. */
@@ -63,5 +128,6 @@ export const AppConfig = z.object({
   agents: AgentsConfig,
   tasking: TaskingConfig,
   messaging: MessagingConfig,
+  setting: SettingConfig.default({ admin_open_ids: [] }),
 });
 export interface AppConfig extends z.infer<typeof AppConfig> {}
diff --git a/src/shared/index.ts b/src/shared/index.ts
index 81f0b9d..8779824 100644
--- a/src/shared/index.ts
+++ b/src/shared/index.ts
@@ -7,3 +7,4 @@ export * from "./sessioning";
 export * from "./skills";
 export * from "./tasking";
 export * from "./utils";
+export * from "./workspaces";
diff --git a/src/shared/logging/index.ts b/src/shared/logging/index.ts
index 9943ebe..b54a1a5 100644
--- a/src/shared/logging/index.ts
+++ b/src/shared/logging/index.ts
@@ -1,5 +1,7 @@
 import pino from "pino";
 
+import * as paths from "../config/paths";
+
 const VALID_LEVELS = ["trace", "debug", "info", "warn", "error"] as const;
 
 function parseLevel(): pino.Level {
@@ -12,17 +14,44 @@ function parseLevel(): pino.Level {
 
 const isProd = process.env.NODE_ENV === "production";
 
+/**
+ * Dual transport: pretty-printed stdout (for dev UX) plus a per-day plain-text
+ * file under `$AGENTARA_HOME/runtime-logs/YYYY-MM-DD.log`. File output is
+ * always at `debug` level regardless of stdout level, so disk captures more
+ * detail than the terminal when we tail back through a past session.
+ * File path is resolved at startup — log rollover happens only on restart.
+ */
+const logFilePath = paths.resolveRuntimeLogFilePath(new Date());
+
 const rootOptions: pino.LoggerOptions = {
-  level: parseLevel(),
-  ...{
-    transport: {
-      target: "pino-pretty",
-      options: {
-        colorize: true,
-        translateTime: isProd ? "SYS:MM-DD HH:MM:ss" : "SYS:HH:MM:ss",
-        ignore: "hostname,pid,topic",
+  // Root level is the floor — each transport target can narrow but not widen.
+  // We set root to "trace" so the file target can capture everything while the
+  // stdout target still respects AGENTARA_LOG_LEVEL.
+  level: "trace",
+  transport: {
+    targets: [
+      {
+        target: "pino-pretty",
+        level: parseLevel(),
+        options: {
+          colorize: true,
+          translateTime: isProd ? "SYS:MM-DD HH:MM:ss" : "SYS:HH:MM:ss",
+          ignore: "hostname,pid,topic",
+        },
+      },
+      {
+        target: "pino-pretty",
+        level: "debug",
+        options: {
+          destination: logFilePath,
+          mkdir: true,
+          colorize: false,
+          translateTime: "SYS:yyyy-mm-dd HH:MM:ss",
+          ignore: "hostname,pid",
+          append: true,
+        },
       },
-    },
+    ],
   },
 };
 
diff --git a/src/shared/messaging/message-channel.ts b/src/shared/messaging/message-channel.ts
index 5da67fe..1452b92 100644
--- a/src/shared/messaging/message-channel.ts
+++ b/src/shared/messaging/message-channel.ts
@@ -1,6 +1,35 @@
 import type EventEmitter from "eventemitter3";
 
-import type { AssistantMessage, UserMessage } from "./types";
+import type { AssistantMessage, CardFooterStats, UserMessage } from "./types";
+
+/**
+ * Payload delivered when a user interacts with an interactive card. The
+ * channel normalizes the provider-specific event (for Feishu:
+ * `card.action.trigger`) into this shape before re-emitting.
+ */
+export interface CardActionPayload {
+  /** ID of the card message the user interacted with. */
+  message_id: string;
+  /** Channel that delivered the event. */
+  channel_id: string;
+  /** Provider-specific chat/group identifier, if applicable. */
+  chat_id?: string;
+  /** open_id of the user who clicked. */
+  operator_open_id: string;
+  /**
+   * Action discriminator. For our own cards, this is set via
+   * `behaviors[].value.action` on the triggering element. Commands use it to
+   * route the event (e.g. `"setup_submit"`).
+   */
+  action_name: string;
+  /** The full `behaviors[].value` dict, passed through verbatim. */
+  value: Record<string, unknown>;
+  /**
+   * For `action_type: "form_submit"` — values of every named field inside the
+   * enclosing form (input/checker/select). Empty for non-form actions.
+   */
+  form_value: Record<string, unknown>;
+}
 
 /** Event types emitted by a message channel. */
 export interface MessageChannelEventTypes {
@@ -8,6 +37,8 @@ export interface MessageChannelEventTypes {
   "message:inbound": (message: UserMessage) => void;
   // eslint-disable-next-line no-unused-vars
   "message:recalled": (messageId: string, channelId: string) => void;
+  // eslint-disable-next-line no-unused-vars
+  "card:action": (payload: CardActionPayload) => void;
 }
 
 /** Abstract message channel for sending and receiving messages. */
@@ -33,7 +64,11 @@ export interface MessageChannel extends EventEmitter {
    * Reply to an existing message.
    * @param messageId - ID of the message to reply to.
    * @param message - The assistant message to send (without id).
-   * @param options - Optional settings (e.g. streaming mode).
+   * @param options - Optional settings.
+   *   - `streaming`: card is part of a stream; skip text rendering until final.
+   *   - `replyInThread`: Feishu-specific — default `true`. Set `false` for
+   *     one-shot replies (e.g. slash commands) that should appear inline in
+   *     the chat instead of opening a new topic.
    * @returns The sent message with id assigned.
    */
   replyMessage(
@@ -42,18 +77,21 @@ export interface MessageChannel extends EventEmitter {
     // eslint-disable-next-line no-unused-vars
     message: Omit<AssistantMessage, "id">,
     // eslint-disable-next-line no-unused-vars
-    options?: { streaming?: boolean },
+    options?: { streaming?: boolean; replyInThread?: boolean },
   ): Promise<AssistantMessage>;
 
   /**
    * Update the content of an existing message.
    * @param message - The assistant message with updated content.
-   * @param options - Optional settings (e.g. streaming mode).
+   * @param options - Optional settings.
+   *   - `streaming`: card is mid-stream; skip final-only rendering.
+   *   - `footer`: context / quota stats to render at the bottom of a
+   *     finalized card. Ignored while streaming.
    */
   updateMessageContent(
     // eslint-disable-next-line no-unused-vars
     message: AssistantMessage,
     // eslint-disable-next-line no-unused-vars
-    options?: { streaming?: boolean },
+    options?: { streaming?: boolean; footer?: CardFooterStats },
   ): Promise<void>;
 }
diff --git a/src/shared/messaging/message-gateway.ts b/src/shared/messaging/message-gateway.ts
index 5e1c7be..223a194 100644
--- a/src/shared/messaging/message-gateway.ts
+++ b/src/shared/messaging/message-gateway.ts
@@ -1,7 +1,7 @@
 import type EventEmitter from "eventemitter3";
 
-import type { MessageChannel } from "./message-channel";
-import type { AssistantMessage, UserMessage } from "./types";
+import type { CardActionPayload, MessageChannel } from "./message-channel";
+import type { AssistantMessage, CardFooterStats, UserMessage } from "./types";
 
 /** Event types emitted by a message gateway. */
 export interface MessageGatewayEventTypes {
@@ -9,6 +9,8 @@ export interface MessageGatewayEventTypes {
   "message:inbound": (message: UserMessage) => void;
   // eslint-disable-next-line no-unused-vars
   "message:recalled": (messageId: string, channelId: string) => void;
+  // eslint-disable-next-line no-unused-vars
+  "card:action": (payload: CardActionPayload) => void;
 }
 
 /**
@@ -26,16 +28,28 @@ export interface MessageGateway extends EventEmitter<MessageGatewayEventTypes> {
   /**
    * Post a new assistant message without replying to an existing message.
    * @param message - The assistant message to post (without id).
+   * @param options - Optional settings. `channelId` bypasses the session→channel
+   *   DB lookup; use it when the session row may not exist yet (e.g. gateway
+   *   commands that reply before any Session is created).
    * @returns The posted message with id assigned.
    */
-  // eslint-disable-next-line no-unused-vars
-  postMessage(message: Omit<AssistantMessage, "id">): Promise<AssistantMessage>;
+  postMessage(
+    // eslint-disable-next-line no-unused-vars
+    message: Omit<AssistantMessage, "id">,
+    // eslint-disable-next-line no-unused-vars
+    options?: { channelId?: string },
+  ): Promise<AssistantMessage>;
 
   /**
    * Reply to an existing message.
    * @param messageId - ID of the message to reply to.
    * @param message - The assistant message to send (without id).
-   * @param options - Optional settings (e.g. streaming mode).
+   * @param options - Optional settings.
+   *   - `channelId` bypasses the session→channel DB lookup; use it when the
+   *     session row may not exist yet.
+   *   - `replyInThread` toggles whether the reply opens a new Feishu topic
+   *     (default `true`, matches the session flow). Pass `false` for one-shot
+   *     replies like slash commands so they show up inline in the chat list.
    * @returns The sent message with id assigned.
    */
   replyMessage(
@@ -44,18 +58,27 @@ export interface MessageGateway extends EventEmitter<MessageGatewayEventTypes> {
     // eslint-disable-next-line no-unused-vars
     message: Omit<AssistantMessage, "id">,
     // eslint-disable-next-line no-unused-vars
-    options?: { streaming?: boolean },
+    options?: {
+      streaming?: boolean;
+      channelId?: string;
+      replyInThread?: boolean;
+    },
   ): Promise<AssistantMessage>;
 
   /**
    * Update the content of an existing message.
    * @param message - The assistant message with updated content.
-   * @param options - Optional settings (e.g. streaming mode).
+   * @param options - Optional settings. `channelId` bypasses the session→channel
+   *   DB lookup. `footer` carries context / quota stats for the finalized card.
    */
   updateMessageContent(
     // eslint-disable-next-line no-unused-vars
     message: AssistantMessage,
     // eslint-disable-next-line no-unused-vars
-    options?: { streaming?: boolean },
+    options?: {
+      streaming?: boolean;
+      channelId?: string;
+      footer?: CardFooterStats;
+    },
   ): Promise<void>;
 }
diff --git a/src/shared/messaging/types/footer.ts b/src/shared/messaging/types/footer.ts
new file mode 100644
index 0000000..44f5bfc
--- /dev/null
+++ b/src/shared/messaging/types/footer.ts
@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+/**
+ * Per-quota window snapshot for the card footer. `utilization` is a
+ * percentage in the `0..100` range (mirrors the Anthropic OAuth usage
+ * API). `resets_at` is an ISO timestamp, or `null` when the window has
+ * no scheduled reset.
+ */
+export const CardFooterQuota = z.object({
+  utilization: z.number(),
+  resets_at: z.string().nullable(),
+});
+export interface CardFooterQuota extends z.infer<typeof CardFooterQuota> {}
+
+/**
+ * Stats rendered at the bottom of a finalized assistant card: how full the
+ * agent's context window is right now, plus the account's rolling-quota
+ * progress. Every field is optional — the card degrades gracefully when a
+ * runner reports no usage or the quota lookup fails.
+ */
+export const CardFooterStats = z.object({
+  /** Resolved model id that served the latest turn, when known. */
+  model: z.string().optional(),
+  /** Context-window occupancy for the latest turn. */
+  context: z
+    .object({
+      used_tokens: z.number(),
+      limit_tokens: z.number(),
+    })
+    .optional(),
+  /** Claude's rolling 5-hour usage window. */
+  five_hour: CardFooterQuota.optional(),
+  /** Claude's rolling 7-day usage window. */
+  seven_day: CardFooterQuota.optional(),
+});
+export interface CardFooterStats extends z.infer<typeof CardFooterStats> {}
diff --git a/src/shared/messaging/types/index.ts b/src/shared/messaging/types/index.ts
index 5119722..01f5d28 100644
--- a/src/shared/messaging/types/index.ts
+++ b/src/shared/messaging/types/index.ts
@@ -1,4 +1,5 @@
 export * from "./contents";
+export * from "./footer";
 export * from "./message";
 export * from "./roles";
 export * from "./tools";
diff --git a/src/shared/messaging/types/message.ts b/src/shared/messaging/types/message.ts
index 34ed596..3a18b32 100644
--- a/src/shared/messaging/types/message.ts
+++ b/src/shared/messaging/types/message.ts
@@ -39,6 +39,22 @@ export const SystemMessage = BaseMessage.extend({
 });
 export interface SystemMessage extends z.infer<typeof SystemMessage> {}
 
+/**
+ * A single @-mention inside an inbound message. Provider-agnostic shape —
+ * Feishu maps these from the event's `mentions` array; other channels may
+ * leave the list empty. Consumers (e.g. `/group`, `/allow`) use this to
+ * resolve `@_user_N` placeholders in the text content back to open_ids.
+ */
+export const MessageMention = z.object({
+  /** Placeholder substring in the text, e.g. `@_user_0` for Feishu. */
+  key: z.string(),
+  /** Provider-specific open_id of the mentioned user. */
+  open_id: z.string(),
+  /** Display name at event time (best-effort). */
+  name: z.string().optional(),
+});
+export interface MessageMention extends z.infer<typeof MessageMention> {}
+
 /**
  * The user message.
  */
@@ -46,6 +62,23 @@ export const UserMessage = BaseMessage.extend({
   role: z.literal("user"),
   /** The channel id this message originated from. */
   channel_id: z.string().optional(),
+  /** Feishu chat_id, when this message originated from a Feishu channel. */
+  chat_id: z.string().optional(),
+  /**
+   * Feishu chat type: "group" for group chats, "single" for 1:1 (P2P).
+   * Only meaningful when `chat_id` is set. Left undefined for non-Feishu
+   * sources so consumers fall back to "permissive" defaults.
+   */
+  chat_type: z.enum(["group", "single"]).optional(),
+  /** Feishu topic/thread id, when the message is inside a topic. */
+  thread_id: z.string().optional(),
+  /** Provider-specific open_id of the sender (e.g. Feishu open_id). */
+  sender_open_id: z.string().optional(),
+  /**
+   * @-mentions carried from the source event, in order. Empty/undefined when
+   * the channel doesn't expose mentions or when no users were @-tagged.
+   */
+  mentions: z.array(MessageMention).optional(),
   content: z.array(
     z.discriminatedUnion("type", [
       TextMessageContent,
@@ -56,6 +89,21 @@ export const UserMessage = BaseMessage.extend({
 });
 export interface UserMessage extends z.infer<typeof UserMessage> {}
 
+/**
+ * Token accounting for a single model turn, mirrored from the agent's
+ * raw response. All fields are optional because not every runner reports
+ * usage (e.g. Codex omits it). The cache fields are part of the context
+ * window occupancy too — Claude counts prompt-cache reads/writes as input
+ * that still occupies the window.
+ */
+export const MessageUsage = z.object({
+  input_tokens: z.number().optional(),
+  output_tokens: z.number().optional(),
+  cache_read_input_tokens: z.number().optional(),
+  cache_creation_input_tokens: z.number().optional(),
+});
+export interface MessageUsage extends z.infer<typeof MessageUsage> {}
+
 /**
  * The assistant message.
  */
@@ -69,6 +117,18 @@ export const AssistantMessage = BaseMessage.extend({
       ToolUseMessageContent,
     ]),
   ),
+  /**
+   * Token usage reported for the turn that produced this message. Used to
+   * derive context-window occupancy for the card footer. Absent for runners
+   * that don't surface usage.
+   */
+  usage: MessageUsage.optional(),
+  /**
+   * Resolved model id the agent actually ran (e.g. `claude-opus-4-1`).
+   * Reported by the runner — the config may leave the model unpinned, so
+   * this is the only reliable source for what served the turn.
+   */
+  model: z.string().optional(),
 });
 export interface AssistantMessage extends z.infer<typeof AssistantMessage> {}
 
diff --git a/src/shared/messaging/utils/index.ts b/src/shared/messaging/utils/index.ts
index 93f9813..0bc10bb 100644
--- a/src/shared/messaging/utils/index.ts
+++ b/src/shared/messaging/utils/index.ts
@@ -4,6 +4,7 @@ import type {
   GlobToolUseMessageContent,
   GrepToolUseMessageContent,
   Message,
+  MessageMention,
   ReadToolUseMessageContent,
   SkillToolUseMessageContent,
   ToolSearchToolUseMessageContent,
@@ -85,6 +86,28 @@ export function extractTextContent(
   return result.join("\n\n").trim();
 }
 
+/**
+ * Replace placeholder `key`s with `@<name>` for each provided mention.
+ *
+ * Feishu delivers @-mentions as opaque `@_user_N` tokens in the message
+ * text plus a sibling `mentions` array carrying the real `open_id` and
+ * `name`. Agent runners call this before serializing the prompt so the
+ * underlying LLM sees `@xluos` instead of `@_user_0`. Keys without a
+ * known name are left as-is.
+ */
+export function inlineMentions(
+  text: string,
+  mentions: MessageMention[] | undefined,
+): string {
+  if (!mentions || mentions.length === 0) return text;
+  let result = text;
+  for (const mention of mentions) {
+    if (!mention.name) continue;
+    result = result.replaceAll(mention.key, `@${mention.name}`);
+  }
+  return result;
+}
+
 function extractToolUse(content: ToolUseMessageContent): string {
   if (content.name === "Task") {
     const toolUse = content as ToolUseMessageContent;
diff --git a/src/shared/sessioning/types/session.ts b/src/shared/sessioning/types/session.ts
index 30ed732..4f094cf 100644
--- a/src/shared/sessioning/types/session.ts
+++ b/src/shared/sessioning/types/session.ts
@@ -15,6 +15,10 @@ export const Session = z.object({
   cwd: z.string(),
   /** The channel id this session belongs to, or null/undefined for legacy sessions. */
   channel_id: z.string().optional().nullable(),
+  /** Feishu chat_id owning this session; null for non-Feishu sessions. */
+  chat_id: z.string().optional().nullable(),
+  /** Feishu topic/thread id for this session; null for non-threaded sessions. */
+  thread_id: z.string().optional().nullable(),
   /** The text content of the session's first inbound message. */
   first_message: z.string(),
   /** Runner-specific session/thread id (e.g. Codex thread id), if available. */
diff --git a/src/shared/tasking/types/payload.ts b/src/shared/tasking/types/payload.ts
index 5e7811c..907b5ae 100644
--- a/src/shared/tasking/types/payload.ts
+++ b/src/shared/tasking/types/payload.ts
@@ -8,6 +8,7 @@ import { UserMessage } from "../../messaging";
 export const InboundMessageTaskPayload = z.object({
   type: z.literal("inbound_message"),
   message: UserMessage,
+  forceNewRunnerSession: z.boolean().optional(),
 });
 export interface InboundMessageTaskPayload extends z.infer<
   typeof InboundMessageTaskPayload
diff --git a/src/shared/utils/index.ts b/src/shared/utils/index.ts
index 8be0f79..0642121 100644
--- a/src/shared/utils/index.ts
+++ b/src/shared/utils/index.ts
@@ -1 +1,2 @@
+export * from "./slugify-workspace-name";
 export * from "./uuid";
diff --git a/src/shared/utils/slugify-workspace-name.ts b/src/shared/utils/slugify-workspace-name.ts
new file mode 100644
index 0000000..fad8c03
--- /dev/null
+++ b/src/shared/utils/slugify-workspace-name.ts
@@ -0,0 +1,31 @@
+/**
+ * Turn an arbitrary string (a Feishu group name, or whatever the user typed
+ * into the `/setup` workspace-name input) into a safe directory name for
+ * `$AGENTARA_HOME/workspaces/<name>/`.
+ *
+ * Design:
+ * - Preserve CJK characters (common in group names) — keeping the directory
+ *   human-readable matters more than strict ASCII.
+ * - Collapse any whitespace run into a single `-`.
+ * - Drop path separators (`/`, `\`), leading dots (would make the dir hidden
+ *   or be interpreted as `.`/`..`), and any control characters.
+ * - Trim leading/trailing separators/whitespace.
+ * - Enforce a sensible length cap so shells/tools don't choke on the path.
+ *
+ * Returns an empty string if nothing usable survives; callers should fall
+ * back to a deterministic chat-id-based name in that case.
+ */
+export function slugifyWorkspaceName(raw: string): string {
+  if (!raw) return "";
+  // eslint-disable-next-line no-control-regex
+  let out = raw.replace(/[\u0000-\u001F\u007F]/g, "");
+  out = out.replace(/\s+/g, "-");
+  out = out.replace(/[\\/]/g, "-");
+  // Strip characters that are dangerous or awkward as directory names.
+  out = out.replace(/[<>:"|?*`$]/g, "");
+  out = out.replace(/^[.\-_\s]+/, "");
+  out = out.replace(/[.\-_\s]+$/, "");
+  out = out.replace(/-{2,}/g, "-");
+  if (out.length > 64) out = out.slice(0, 64).replace(/-+$/, "");
+  return out;
+}
diff --git a/src/shared/workspaces/index.ts b/src/shared/workspaces/index.ts
new file mode 100644
index 0000000..eea524d
--- /dev/null
+++ b/src/shared/workspaces/index.ts
@@ -0,0 +1 @@
+export * from "./types";
diff --git a/src/shared/workspaces/types/group-workspace.ts b/src/shared/workspaces/types/group-workspace.ts
new file mode 100644
index 0000000..0be8a6c
--- /dev/null
+++ b/src/shared/workspaces/types/group-workspace.ts
@@ -0,0 +1,41 @@
+import { z } from "zod";
+
+import { Workspace } from "./workspace";
+
+/**
+ * A persisted per-group workspace binding, flattened for callers.
+ *
+ * Each Feishu group that has been bound via `/bind` or `/setup` owns one row
+ * in `group_workspaces`, but the underlying workspace itself lives in the
+ * separate `workspaces` registry so multiple groups can reference the same
+ * directory by stable `workspace_id`. The store joins them and returns this
+ * flattened shape so callers don't need to know the split.
+ *
+ * `active_repo`/`active_branch` come from the workspace row — groups sharing
+ * a workspace see the same active state because only one `.git/HEAD` exists
+ * per cloned repo. `created_at`/`updated_at` are the binding timestamps.
+ */
+export const GroupWorkspace = z.object({
+  /** Feishu chat id. */
+  chat_id: z.string(),
+  /** Stable workspace id. */
+  workspace_id: z.string(),
+  /** Human-readable workspace name (from workspaces). */
+  workspace_name: z.string(),
+  /** Absolute path of the workspace root (from workspaces). */
+  workspace_path: z.string(),
+  /** Basename of the active repo (from workspaces), or null. */
+  active_repo: z.string().nullable(),
+  /** Git branch the active repo should be on (from workspaces), or null. */
+  active_branch: z.string().nullable(),
+  /** Epoch ms when the binding was created. */
+  created_at: z.number(),
+  /** Epoch ms when the binding was last updated. */
+  updated_at: z.number(),
+});
+export interface GroupWorkspace extends z.infer<typeof GroupWorkspace> {}
+
+export const WorkspaceBinding = GroupWorkspace.extend({
+  workspace: Workspace.optional(),
+});
+export interface WorkspaceBinding extends z.infer<typeof WorkspaceBinding> {}
diff --git a/src/shared/workspaces/types/index.ts b/src/shared/workspaces/types/index.ts
new file mode 100644
index 0000000..87e68f8
--- /dev/null
+++ b/src/shared/workspaces/types/index.ts
@@ -0,0 +1,2 @@
+export * from "./group-workspace";
+export * from "./workspace";
diff --git a/src/shared/workspaces/types/workspace.ts b/src/shared/workspaces/types/workspace.ts
new file mode 100644
index 0000000..60d1cb8
--- /dev/null
+++ b/src/shared/workspaces/types/workspace.ts
@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+/**
+ * A reusable workspace entity with a stable id.
+ *
+ * The `name` remains human-readable for operators, while `id` is what other
+ * groups can use to bind to the exact same workspace directory later.
+ *
+ * `active_repo`/`active_branch` live on the workspace (not the binding)
+ * because only one `.git/HEAD` exists per cloned repo — the "active"
+ * state is a property of the directory on disk, shared across all groups
+ * bound to the workspace.
+ */
+export const Workspace = z.object({
+  /** Stable workspace id. */
+  id: z.string(),
+  /** Human-readable workspace name. */
+  name: z.string(),
+  /** Absolute path of the workspace root. */
+  path: z.string(),
+  /** Basename of the currently focused repo under `path`, or null. */
+  active_repo: z.string().nullable(),
+  /** Git branch to check out in the active repo on dispatch, or null. */
+  active_branch: z.string().nullable(),
+  /** Epoch ms when the workspace was created. */
+  created_at: z.number(),
+  /** Epoch ms when the workspace was last updated. */
+  updated_at: z.number(),
+  /** Epoch ms of the last dispatch/bind/active-state mutation. */
+  last_active_at: z.number(),
+});
+export interface Workspace extends z.infer<typeof Workspace> {}
diff --git a/tests/community/anthropic/claude-usage.test.ts b/tests/community/anthropic/claude-usage.test.ts
new file mode 100644
index 0000000..5c44db1
--- /dev/null
+++ b/tests/community/anthropic/claude-usage.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, test } from "bun:test";
+
+import { contextLimitForModel } from "@/community/anthropic";
+
+describe("contextLimitForModel", () => {
+  test("defaults to the 1M long-context window", () => {
+    expect(contextLimitForModel(undefined)).toBe(1_000_000);
+    expect(contextLimitForModel("claude-opus-4-7")).toBe(1_000_000);
+    expect(contextLimitForModel("claude-sonnet-4-5[1m]")).toBe(1_000_000);
+  });
+});
diff --git a/tests/community/feishu/message-renderer.test.ts b/tests/community/feishu/message-renderer.test.ts
new file mode 100644
index 0000000..6646a07
--- /dev/null
+++ b/tests/community/feishu/message-renderer.test.ts
@@ -0,0 +1,236 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  MAX_MARKDOWN_BYTES_PER_CHUNK,
+  MAX_STEP_TEXT_CHARS,
+  MAX_STEPS_PER_CARD,
+  renderMessageCard,
+  splitMarkdownByBytes,
+  splitMarkdownForCards,
+} from "@/community/feishu/messaging/message-renderer";
+import type { AssistantMessage } from "@/shared";
+
+type StepElement = {
+  tag: "div";
+  text: { content: string };
+};
+
+const thinking = (text: string) =>
+  ({ type: "thinking", thinking: text }) as const;
+const toolUse = (name: string, input: Record<string, unknown> = {}) =>
+  ({
+    type: "tool_use",
+    id: `t-${name}`,
+    name,
+    input,
+  }) as const;
+const noopUpload = async (p: string) => p;
+
+describe("renderMessageCard step panel", () => {
+  test("renders one step per thinking/tool_use block up to the cap", async () => {
+    const content = [
+      thinking("hello"),
+      toolUse("Read", { file_path: "/tmp/x" }),
+    ] as AssistantMessage["content"];
+    const card = await renderMessageCard(content, {
+      streaming: true,
+      uploadImage: noopUpload,
+    });
+    const panel = card.body.elements[0] as { elements: StepElement[] };
+    expect(panel.elements).toHaveLength(2);
+    expect(panel.elements[0]!.text.content).toBe("hello");
+  });
+
+  test("keeps only the last N-1 rows + an ellipsis summary on overflow", async () => {
+    const content: AssistantMessage["content"] = [];
+    for (let i = 0; i < 66; i++) {
+      content.push(toolUse("Bash", { description: `step ${i}` }));
+    }
+    const card = await renderMessageCard(content, {
+      streaming: true,
+      uploadImage: noopUpload,
+    });
+    const panel = card.body.elements[0] as {
+      elements: StepElement[];
+      header: { title: { content: string } };
+    };
+    expect(panel.elements).toHaveLength(MAX_STEPS_PER_CARD);
+    // Top row is the ellipsis summary
+    expect(panel.elements[0]!.text.content).toMatch(/^… \d+ earlier steps$/);
+    // Header shows the TRUE count, not the windowed view size
+    expect(panel.header.title.content).toBe("Working on it (66 steps)");
+    // Tail preserves the most recent steps
+    expect(panel.elements[panel.elements.length - 1]!.text.content).toBe(
+      "step 65",
+    );
+  });
+
+  test("per-step text is clipped to the single-line char cap", async () => {
+    const hugeDesc = "x".repeat(MAX_STEP_TEXT_CHARS + 500);
+    const content = [
+      toolUse("Bash", { description: hugeDesc }),
+    ] as AssistantMessage["content"];
+    const card = await renderMessageCard(content, {
+      streaming: true,
+      uploadImage: noopUpload,
+    });
+    const panel = card.body.elements[0] as { elements: StepElement[] };
+    expect(panel.elements[0]!.text.content.length).toBeLessThanOrEqual(
+      MAX_STEP_TEXT_CHARS,
+    );
+    expect(panel.elements[0]!.text.content.endsWith("…")).toBe(true);
+  });
+
+  test("multi-line text is clipped to the first line with ellipsis hint", async () => {
+    const multiline = "first line\nsecond line\nthird line";
+    const content = [thinking(multiline)] as AssistantMessage["content"];
+    const card = await renderMessageCard(content, {
+      streaming: true,
+      uploadImage: noopUpload,
+    });
+    const panel = card.body.elements[0] as { elements: StepElement[] };
+    expect(panel.elements[0]!.text.content).toBe("first line …");
+  });
+});
+
+describe("renderMessageCard final text", () => {
+  test("summary preview stays short when the final markdown is huge", async () => {
+    const bigMarkdown = "# Title\n\n" + "x".repeat(10_000);
+    const content = [
+      { type: "text", text: bigMarkdown },
+    ] as AssistantMessage["content"];
+    const card = await renderMessageCard(content, {
+      streaming: false,
+      uploadImage: noopUpload,
+    });
+    const summary = (card.config as { summary: { content: string } }).summary
+      .content;
+    // Body still carries the full markdown
+    const body = card.body.elements.find(
+      (e) => (e as { tag: string }).tag === "markdown",
+    ) as { content: string } | undefined;
+    expect(body?.content.length).toBeGreaterThan(5000);
+    // Summary is a preview — nowhere near the full markdown length
+    expect(summary.length).toBeLessThan(500);
+  });
+});
+
+describe("renderMessageCard footer stats", () => {
+  const findFooter = (card: Awaited<ReturnType<typeof renderMessageCard>>) =>
+    card.body.elements
+      .map((e) => e as { tag: string; text?: { content: string } })
+      .filter((e) => e.tag === "div" && typeof e.text?.content === "string")
+      .map((e) => e.text!.content)
+      .find((c) => c.includes("Context") || c.includes("limit"));
+
+  test("renders context + quota progress bars on a finalized card", async () => {
+    const content = [
+      { type: "text", text: "done" },
+    ] as AssistantMessage["content"];
+    const card = await renderMessageCard(content, {
+      streaming: false,
+      uploadImage: noopUpload,
+      elapsedMs: 1200,
+      footer: {
+        model: "claude-opus-4-1",
+        context: { used_tokens: 50_000, limit_tokens: 200_000 },
+        five_hour: { utilization: 18, resets_at: null },
+        seven_day: { utilization: 52, resets_at: null },
+      },
+    });
+    const footer = findFooter(card);
+    expect(footer).toBeDefined();
+    expect(footer).toContain("Done in");
+    expect(footer).toContain("Model");
+    expect(footer).toContain("claude-opus-4-1");
+    expect(footer).toContain("Context");
+    expect(footer).toContain("25%"); // 50k / 200k
+    expect(footer).toContain("50k/200k");
+    expect(footer).toContain("5h limit");
+    expect(footer).toContain("18%");
+    expect(footer).toContain("Weekly");
+    expect(footer).toContain("52%");
+    expect(footer).toMatch(/[█░]/);
+  });
+
+  test("renders the 1M window as '1M' and never overflows 100%", async () => {
+    const content = [
+      { type: "text", text: "done" },
+    ] as AssistantMessage["content"];
+    const card = await renderMessageCard(content, {
+      streaming: false,
+      uploadImage: noopUpload,
+      footer: {
+        context: { used_tokens: 339_000, limit_tokens: 1_000_000 },
+      },
+    });
+    const footer = findFooter(card);
+    expect(footer).toContain("339k/1M");
+    expect(footer).toContain("34%");
+    expect(footer).not.toContain("100%");
+  });
+
+  test("omits bars while streaming", async () => {
+    const content = [thinking("x")] as AssistantMessage["content"];
+    const card = await renderMessageCard(content, {
+      streaming: true,
+      uploadImage: noopUpload,
+      footer: { context: { used_tokens: 1, limit_tokens: 2 } },
+    });
+    expect(findFooter(card)).toBeUndefined();
+  });
+
+  test("no footer element when there are no stats and no elapsed time", async () => {
+    const content = [
+      { type: "text", text: "done" },
+    ] as AssistantMessage["content"];
+    const card = await renderMessageCard(content, {
+      streaming: false,
+      uploadImage: noopUpload,
+    });
+    expect(findFooter(card)).toBeUndefined();
+  });
+});
+
+describe("splitMarkdownByBytes", () => {
+  test("returns a single chunk when already under budget", () => {
+    const chunks = splitMarkdownByBytes("hello world", 1024);
+    expect(chunks).toEqual(["hello world"]);
+  });
+
+  test("splits at paragraph boundaries when over budget", () => {
+    const paragraph = "x".repeat(600);
+    const markdown = [paragraph, paragraph, paragraph].join("\n\n");
+    const chunks = splitMarkdownByBytes(markdown, 800);
+    expect(chunks.length).toBeGreaterThan(1);
+    for (const chunk of chunks) {
+      expect(chunk.length).toBeLessThanOrEqual(1600); // well under 2x budget
+    }
+    // Content is preserved: concatenating chunks recovers the paragraphs
+    const joined = chunks.join("\n\n");
+    expect(joined).toContain(paragraph);
+  });
+
+  test("falls back to line splitting when a single paragraph is oversized", () => {
+    const lines: string[] = [];
+    for (let i = 0; i < 20; i++) lines.push("x".repeat(500));
+    const markdown = lines.join("\n"); // one paragraph, many lines
+    const chunks = splitMarkdownByBytes(markdown, 1024);
+    expect(chunks.length).toBeGreaterThan(1);
+  });
+});
+
+describe("splitMarkdownForCards", () => {
+  test("caps at 5 tables per chunk AND respects byte budget", () => {
+    const table = "| a | b |\n|---|---|\n| 1 | 2 |\n";
+    const markdown = Array(12).fill(table).join("\n");
+    const chunks = splitMarkdownForCards(markdown);
+    // 12 tables > 5 per chunk → at least 3 chunks
+    expect(chunks.length).toBeGreaterThanOrEqual(3);
+  });
+
+  test("MAX_MARKDOWN_BYTES_PER_CHUNK sits safely below Feishu's body cap", () => {
+    expect(MAX_MARKDOWN_BYTES_PER_CHUNK).toBeGreaterThan(0);
+    expect(MAX_MARKDOWN_BYTES_PER_CHUNK).toBeLessThan(30 * 1024);
+  });
+});
diff --git a/tests/community/feishu/messaging/message-renderer.test.ts b/tests/community/feishu/messaging/message-renderer.test.ts
index 013b005..d6376d2 100644
--- a/tests/community/feishu/messaging/message-renderer.test.ts
+++ b/tests/community/feishu/messaging/message-renderer.test.ts
@@ -1,6 +1,9 @@
 import { describe, expect, test } from "bun:test";
 
-import { renderMessageCard } from "@/community/feishu/messaging/message-renderer";
+import {
+  MAX_STEPS_PER_CARD,
+  renderMessageCard,
+} from "@/community/feishu/messaging/message-renderer";
 
 function countElements(value: unknown): number {
   if (!value || typeof value !== "object") {
@@ -43,6 +46,6 @@ describe("renderMessageCard", () => {
 
     expect(countElements(card)).toBeLessThanOrEqual(200);
     expect(stepPanel?.tag).toBe("collapsible_panel");
-    expect(stepPanel?.elements.length).toBe(65);
+    expect(stepPanel?.elements.length).toBe(MAX_STEPS_PER_CARD);
   });
 });
diff --git a/tests/community/openai/codex-agent-runner.test.ts b/tests/community/openai/codex-agent-runner.test.ts
index bfa2f4f..a4dc81a 100644
--- a/tests/community/openai/codex-agent-runner.test.ts
+++ b/tests/community/openai/codex-agent-runner.test.ts
@@ -431,4 +431,35 @@ describe("CodexAgentRunner._parseStreamLine", () => {
     expect(args).toContain("--dangerously-bypass-approvals-and-sandbox");
     expect(args).not.toContain("--full-auto");
   });
+
+  test("inserts configured extra global args before exec", () => {
+    const runner = new CodexAgentRunner({
+      extraGlobalArgs: ["--search"],
+    }) as unknown as Record<string, CallableFunction>;
+    const args = runner["_buildExecArgs"]!({
+      isNew: true,
+      resumeId: "unused",
+      prompt: "\"hello\"",
+    }) as string[];
+
+    expect(args).toContain("--dangerously-bypass-approvals-and-sandbox");
+    expect(args.slice(0, 3)).toEqual(["codex", "--search", "exec"]);
+    expect(args.at(-1)).toBe("\"hello\"");
+  });
+
+  test("detects missing Codex resume rollout errors", () => {
+    const runner = new CodexAgentRunner() as unknown as Record<
+      string,
+      CallableFunction
+    >;
+
+    expect(
+      runner["_isMissingResumeErrorText"]!(
+        "Error: thread/resume: thread/resume failed: no rollout found for thread id 249fe9f1",
+      ),
+    ).toBe(true);
+    expect(runner["_isMissingResumeErrorText"]!("some other error")).toBe(
+      false,
+    );
+  });
 });
diff --git a/tests/kernel/agent-failure.test.ts b/tests/kernel/agent-failure.test.ts
new file mode 100644
index 0000000..90f5b34
--- /dev/null
+++ b/tests/kernel/agent-failure.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildAgentCancelledContent,
+  buildAgentFailureContent,
+} from "@/kernel/agent-failure";
+
+describe("buildAgentFailureContent", () => {
+  test("renders cancellation separately from failures", () => {
+    expect(buildAgentCancelledContent()).toEqual([
+      {
+        type: "text",
+        text: "⏹️ 任务已取消。",
+      },
+    ]);
+  });
+
+  test("renders runner startup failures as visible assistant text", () => {
+    const content = buildAgentFailureContent(
+      new Error("检测到当前出口 IP 不在美国（country=CN）"),
+    );
+
+    expect(content).toEqual([
+      {
+        type: "text",
+        text: expect.stringContaining("Agent 启动或执行失败"),
+      },
+    ]);
+    const first = content[0]!;
+    if (first.type !== "text") throw new Error("expected text content");
+    expect(first.text).toContain("country=CN");
+    expect(first.text).toContain("/agent use <type>");
+  });
+
+  test("falls back for non-Error throws", () => {
+    const content = buildAgentFailureContent("boom");
+
+    const first = content[0]!;
+    if (first.type !== "text") throw new Error("expected text content");
+    expect(first.text).toContain("boom");
+  });
+});
diff --git a/tests/kernel/agents/aliases.test.ts b/tests/kernel/agents/aliases.test.ts
new file mode 100644
index 0000000..bb26ff0
--- /dev/null
+++ b/tests/kernel/agents/aliases.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isLegacyAgentTypeAlias,
+  resolveAgentTypeAlias,
+} from "@/kernel/agents";
+
+describe("agent type aliases", () => {
+  test("maps removed codex-gated sessions to codex-yolo", () => {
+    expect(resolveAgentTypeAlias("codex-gated")).toBe("codex-yolo");
+    expect(isLegacyAgentTypeAlias("codex-gated")).toBe(true);
+  });
+
+  test("leaves current runner types unchanged", () => {
+    expect(resolveAgentTypeAlias("codex-yolo")).toBe("codex-yolo");
+    expect(resolveAgentTypeAlias("codex")).toBe("codex");
+    expect(isLegacyAgentTypeAlias("codex-yolo")).toBe(false);
+  });
+});
diff --git a/tests/kernel/codex-resume-card.test.ts b/tests/kernel/codex-resume-card.test.ts
new file mode 100644
index 0000000..6b68c5d
--- /dev/null
+++ b/tests/kernel/codex-resume-card.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildCodexResumeMissingCard,
+  CODEX_RESUME_RESTART_ACTION,
+  formatCodexResumeMissingText,
+} from "@/kernel/codex-resume-card";
+
+describe("codex resume recovery card", () => {
+  test("renders a restart callback button", () => {
+    const card = buildCodexResumeMissingCard({ resumeId: "thread-123" });
+    const buttonRow = card.body.elements.at(-1);
+
+    expect(card.config?.summary.content).toBe("Codex 续接失败");
+    expect(JSON.stringify(card)).toContain("thread-123");
+    expect(buttonRow).toMatchObject({
+      tag: "column_set",
+      columns: [
+        {
+          elements: [
+            {
+              tag: "button",
+              text: { content: "重新开始 Codex 会话" },
+              behaviors: [
+                {
+                  type: "callback",
+                  value: { action: CODEX_RESUME_RESTART_ACTION },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("text fallback tells users it will not auto restart", () => {
+    const text = formatCodexResumeMissingText("thread-123");
+
+    expect(text).toContain("thread-123");
+    expect(text).toContain("不会自动重开");
+  });
+});
diff --git a/tests/kernel/commands/agent-command.test.ts b/tests/kernel/commands/agent-command.test.ts
new file mode 100644
index 0000000..26bc165
--- /dev/null
+++ b/tests/kernel/commands/agent-command.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  getRuntimeDefaultAgentType,
+  setRuntimeDefaultAgentType,
+} from "@/kernel/agents";
+import {
+  CommandRegistry,
+  type CommandContext,
+  type CommandHandler,
+} from "@/kernel/commands";
+
+function getHandler(name: string): CommandHandler {
+  const handler = new CommandRegistry().get(name);
+  if (!handler) throw new Error(`missing command handler: ${name}`);
+  return handler;
+}
+
+function makeContext(args: string[]): CommandContext {
+  return {
+    args,
+    raw: `/${args.join(" ")}`,
+    message: {
+      id: "msg_1",
+      role: "user",
+      session_id: "session_1",
+      channel_id: "ch_1",
+      chat_id: "oc_1",
+      chat_type: "group",
+      content: [{ type: "text", text: "/agent" }],
+    },
+    workspaceStore: {},
+    feishuChannels: new Map(),
+    logger: {
+      info() {},
+      warn() {},
+      error() {},
+      debug() {},
+      trace() {},
+      fatal() {},
+      child() {
+        return this;
+      },
+    },
+  } as unknown as CommandContext;
+}
+
+describe("agent management commands", () => {
+  test("/agents lists available runners and marks the active one", async () => {
+    setRuntimeDefaultAgentType("codex");
+    const result = await getHandler("agents").execute(makeContext([]));
+
+    expect(typeof result).not.toBe("string");
+    if (typeof result === "string") throw new Error("expected card result");
+    expect(result.fallback_text).toContain("当前默认 Agent");
+    expect(result.fallback_text).toContain("可选 Agent");
+    expect(result.fallback_text).toContain("`codex`");
+    expect(result.fallback_text).toContain("当前");
+  });
+
+  test("/agent use switches the runtime default for new sessions", async () => {
+    setRuntimeDefaultAgentType("claude");
+    const result = await getHandler("agent").execute(
+      makeContext(["use", "dummy"]),
+    );
+
+    expect(getRuntimeDefaultAgentType()).toBe("dummy");
+    expect(typeof result).not.toBe("string");
+    if (typeof result === "string") throw new Error("expected card result");
+    expect(result.fallback_text).toContain("dummy");
+    expect(result.fallback_text).toContain("新 session");
+  });
+
+  test("/agent accepts a direct runner type shorthand", async () => {
+    setRuntimeDefaultAgentType("claude");
+    await getHandler("agent").execute(makeContext(["codex"]));
+
+    expect(getRuntimeDefaultAgentType()).toBe("codex");
+  });
+
+  test("/agent matches runner types case-insensitively", async () => {
+    setRuntimeDefaultAgentType("claude");
+    await getHandler("agent").execute(makeContext(["Codex"]));
+
+    expect(getRuntimeDefaultAgentType()).toBe("codex");
+  });
+
+  test("/agent rejects unknown runner types with the available list", async () => {
+    const result = await getHandler("agent").execute(makeContext(["missing"]));
+
+    expect(typeof result).not.toBe("string");
+    if (typeof result === "string") throw new Error("expected card result");
+    expect(result.fallback_text).toContain("未知 Agent");
+    expect(result.fallback_text).toContain("可选 Agent");
+    expect(result.fallback_text).toContain("`codex`");
+  });
+});
diff --git a/tests/kernel/commands/new-command.test.ts b/tests/kernel/commands/new-command.test.ts
new file mode 100644
index 0000000..9c9014b
--- /dev/null
+++ b/tests/kernel/commands/new-command.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildNewCommandRejectionReply,
+  buildNewCommandUsageReply,
+  createFreshUserMessage,
+  extractNewPrompt,
+  isNewCommand,
+} from "@/kernel/commands";
+import type { UserMessage } from "@/shared";
+
+function _makeUserMessage(overrides: Partial<UserMessage> = {}): UserMessage {
+  return {
+    id: "msg_1",
+    role: "user",
+    session_id: "old_session",
+    channel_id: "ch_1",
+    chat_id: "oc_1",
+    chat_type: "group",
+    thread_id: undefined,
+    sender_open_id: "ou_alice",
+    mentions: [],
+    content: [{ type: "text", text: "/new hello" }],
+    ...overrides,
+  };
+}
+
+describe("isNewCommand", () => {
+  test("matches bare /new and /new with args", () => {
+    expect(isNewCommand("/new")).toBe(true);
+    expect(isNewCommand("/new hello")).toBe(true);
+    expect(isNewCommand("/new multi word prompt")).toBe(true);
+  });
+
+  test("rejects slashes that only share the prefix", () => {
+    expect(isNewCommand("/newz")).toBe(false);
+    expect(isNewCommand("/newhello")).toBe(false);
+    expect(isNewCommand("/ new")).toBe(false);
+  });
+
+  test("rejects non-/new input", () => {
+    expect(isNewCommand("hello /new")).toBe(false);
+    expect(isNewCommand("/")).toBe(false);
+    expect(isNewCommand("")).toBe(false);
+  });
+});
+
+describe("extractNewPrompt", () => {
+  test("returns empty string for bare /new", () => {
+    expect(extractNewPrompt("/new")).toBe("");
+  });
+
+  test("returns empty when args are only whitespace", () => {
+    expect(extractNewPrompt("/new ")).toBe("");
+    expect(extractNewPrompt("/new   ")).toBe("");
+  });
+
+  test("trims outer whitespace but preserves inner spacing", () => {
+    expect(extractNewPrompt("/new hello world")).toBe("hello world");
+    expect(extractNewPrompt("/new   hello   ")).toBe("hello");
+    expect(extractNewPrompt("/new hello   world")).toBe("hello   world");
+  });
+
+  test("returns empty for inputs that are not /new", () => {
+    expect(extractNewPrompt("/newz hello")).toBe("");
+    expect(extractNewPrompt("hello")).toBe("");
+    expect(extractNewPrompt("")).toBe("");
+  });
+});
+
+describe("createFreshUserMessage", () => {
+  test("overrides session_id, clears thread_id, replaces content", () => {
+    const original = _makeUserMessage({
+      session_id: "old_session",
+      thread_id: "om_thread_1",
+    });
+    const fresh = createFreshUserMessage(original, "hello", "new_session");
+
+    expect(fresh.session_id).toBe("new_session");
+    expect(fresh.thread_id).toBeUndefined();
+    expect(fresh.content).toEqual([{ type: "text", text: "hello" }]);
+  });
+
+  test("preserves id, channel_id, chat_id, role, chat_type, sender_open_id", () => {
+    const original = _makeUserMessage();
+    const fresh = createFreshUserMessage(original, "hello", "s2");
+
+    expect(fresh.id).toBe(original.id);
+    expect(fresh.channel_id).toBe(original.channel_id);
+    expect(fresh.chat_id).toBe(original.chat_id);
+    expect(fresh.chat_type).toBe(original.chat_type);
+    expect(fresh.sender_open_id).toBe(original.sender_open_id);
+    expect(fresh.role).toBe("user");
+  });
+
+  test("does not mutate the original message", () => {
+    const original = _makeUserMessage({ thread_id: "om_t1" });
+    const snapshot = JSON.stringify(original);
+    createFreshUserMessage(original, "hello", "s2");
+    expect(JSON.stringify(original)).toBe(snapshot);
+  });
+
+  test("clears thread_id even when original had none", () => {
+    const original = _makeUserMessage({ thread_id: undefined });
+    const fresh = createFreshUserMessage(original, "hi", "s_new");
+    expect(fresh.thread_id).toBeUndefined();
+    expect(fresh.session_id).toBe("s_new");
+  });
+});
+
+describe("buildNewCommandRejectionReply", () => {
+  test("fallback text explains main-chat constraint", () => {
+    const reply = buildNewCommandRejectionReply();
+    expect(reply.text).toContain("主群");
+    expect(reply.text).toContain("话题");
+  });
+
+  test("card carries elements beyond just the title", () => {
+    const reply = buildNewCommandRejectionReply();
+    expect(reply.card.body.elements.length).toBeGreaterThan(1);
+  });
+});
+
+describe("buildNewCommandUsageReply", () => {
+  test("fallback text shows usage hint", () => {
+    const reply = buildNewCommandUsageReply();
+    expect(reply.text).toContain("/new");
+  });
+
+  test("card body is populated", () => {
+    const reply = buildNewCommandUsageReply();
+    expect(reply.card.body.elements.length).toBeGreaterThan(1);
+  });
+});
diff --git a/tests/kernel/commands/parser.test.ts b/tests/kernel/commands/parser.test.ts
new file mode 100644
index 0000000..87ca0ca
--- /dev/null
+++ b/tests/kernel/commands/parser.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseCommand } from "@/kernel/commands";
+
+describe("parseCommand", () => {
+  test("parses a bare command", () => {
+    expect(parseCommand("/ls")).toEqual({
+      name: "ls",
+      args: [],
+      raw: "/ls",
+    });
+  });
+
+  test("parses a command with args", () => {
+    expect(parseCommand("/bind ws_123")).toEqual({
+      name: "bind",
+      args: ["ws_123"],
+      raw: "/bind ws_123",
+    });
+  });
+
+  test("lowercases the command name but preserves arg case", () => {
+    expect(parseCommand("/STATUS WS_123")).toMatchObject({
+      name: "status",
+      args: ["WS_123"],
+    });
+  });
+
+  test("splits args on whitespace runs", () => {
+    expect(parseCommand("/clone   url   alias")).toMatchObject({
+      args: ["url", "alias"],
+    });
+  });
+
+  test("trims outer whitespace", () => {
+    expect(parseCommand("  /ls  ")).toMatchObject({ name: "ls" });
+  });
+
+  test("returns null for non-slash input", () => {
+    expect(parseCommand("hello")).toBeNull();
+    expect(parseCommand("")).toBeNull();
+    expect(parseCommand("  ")).toBeNull();
+  });
+
+  test("returns null for bare slash", () => {
+    expect(parseCommand("/")).toBeNull();
+    expect(parseCommand(" / ")).toBeNull();
+  });
+});
diff --git a/tests/kernel/commands/passthrough.test.ts b/tests/kernel/commands/passthrough.test.ts
new file mode 100644
index 0000000..a84349f
--- /dev/null
+++ b/tests/kernel/commands/passthrough.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+
+import { isPassthroughCommand } from "@/kernel/commands";
+
+describe("isPassthroughCommand", () => {
+  test("whitelists /compact", () => {
+    expect(isPassthroughCommand("compact")).toBe(true);
+  });
+
+  test("is case-insensitive", () => {
+    expect(isPassthroughCommand("COMPACT")).toBe(true);
+  });
+
+  test("rejects non-whitelisted commands", () => {
+    expect(isPassthroughCommand("clear")).toBe(false);
+    expect(isPassthroughCommand("context")).toBe(false);
+    expect(isPassthroughCommand("halp")).toBe(false);
+  });
+});
diff --git a/tests/kernel/commands/topic-command.test.ts b/tests/kernel/commands/topic-command.test.ts
new file mode 100644
index 0000000..bfdaf18
--- /dev/null
+++ b/tests/kernel/commands/topic-command.test.ts
@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  CommandRegistry,
+  type CommandContext,
+  type CommandHandler,
+} from "@/kernel/commands";
+
+function getHandler(name: string): CommandHandler {
+  const handler = new CommandRegistry().get(name);
+  if (!handler) throw new Error(`missing command handler: ${name}`);
+  return handler;
+}
+
+interface ContextOverrides {
+  thread_id?: string;
+  chat_id?: string;
+  chat_type?: "group" | "single";
+  channel_id?: string;
+  session?: { agent_type: string; runner_session_id: string | null };
+  thread_auto_respond?: boolean;
+}
+
+function makeContext(overrides: ContextOverrides = {}): CommandContext {
+  return {
+    args: [],
+    raw: "/topic",
+    message: {
+      id: "msg_1",
+      role: "user",
+      session_id: "session_1",
+      channel_id: overrides.channel_id ?? "ch_1",
+      chat_id: overrides.chat_id ?? "oc_1",
+      chat_type: overrides.chat_type ?? "group",
+      thread_id: overrides.thread_id,
+      content: [{ type: "text", text: "/topic" }],
+    },
+    workspaceStore: {},
+    feishuChannels: new Map([
+      [
+        overrides.channel_id ?? "ch_1",
+        {
+          getThreadInfo() {
+            if (overrides.thread_auto_respond === undefined) return undefined;
+            return {
+              session_id: "session_1",
+              auto_respond: overrides.thread_auto_respond,
+            };
+          },
+        },
+      ],
+    ]),
+    sessionManager: {
+      getSession() {
+        return overrides.session
+          ? {
+              id: "session_1",
+              agent_type: overrides.session.agent_type,
+              cwd: "/tmp",
+              first_message: "",
+              runner_session_id: overrides.session.runner_session_id,
+              last_message_created_at: null,
+              created_at: 0,
+              updated_at: 0,
+            }
+          : undefined;
+      },
+    },
+    logger: {
+      info() {},
+      warn() {},
+      error() {},
+      debug() {},
+      trace() {},
+      fatal() {},
+      child() {
+        return this;
+      },
+    },
+  } as unknown as CommandContext;
+}
+
+describe("/topic command", () => {
+  test("renders session and chat identifiers", async () => {
+    const result = await getHandler("topic").execute(
+      makeContext({
+        thread_id: "omt_xyz",
+        session: { agent_type: "claude-code", runner_session_id: "run_42" },
+        thread_auto_respond: false,
+      }),
+    );
+    expect(typeof result).not.toBe("string");
+    if (typeof result === "string") throw new Error("expected card result");
+    expect(result.fallback_text).toContain("话题信息");
+    expect(result.fallback_text).toContain("`session_1`");
+    expect(result.fallback_text).toContain("`omt_xyz`");
+    expect(result.fallback_text).toContain("`oc_1 (群聊)`");
+    expect(result.fallback_text).toContain("群聊");
+    expect(result.fallback_text).toContain("claude-code");
+    expect(result.fallback_text).toContain("`run_42`");
+    expect(result.fallback_text).toContain("话题免 @");
+    expect(result.fallback_text).toContain("默认，需 @ 机器人");
+  });
+
+  test("notes a missing thread context outside topics", async () => {
+    const result = await getHandler("topic").execute(
+      makeContext({
+        session: { agent_type: "codex", runner_session_id: null },
+      }),
+    );
+    if (typeof result === "string") throw new Error("expected card result");
+    expect(result.fallback_text).toContain("(不在话题内)");
+    expect(result.fallback_text).toContain("(尚未建立)");
+    expect(result.fallback_text).not.toContain("话题免 @");
+  });
+
+  test("flags missing session row", async () => {
+    const result = await getHandler("topic").execute(makeContext({}));
+    if (typeof result === "string") throw new Error("expected card result");
+    expect(result.fallback_text).toContain("数据库尚无该 session 记录");
+  });
+});
diff --git a/tests/kernel/commands/unknown-command.test.ts b/tests/kernel/commands/unknown-command.test.ts
new file mode 100644
index 0000000..40d4b10
--- /dev/null
+++ b/tests/kernel/commands/unknown-command.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildUnknownCommandReply } from "@/kernel/commands";
+
+describe("buildUnknownCommandReply", () => {
+  test("names the offending command when parseable", () => {
+    const reply = buildUnknownCommandReply("/halp");
+    expect(reply.text).toContain("/halp");
+    expect(reply.text).toContain("/help");
+  });
+
+  test("names the command even when args follow", () => {
+    const reply = buildUnknownCommandReply("/foo bar baz");
+    expect(reply.text).toContain("/foo");
+  });
+
+  test("lowercases command name in the message", () => {
+    const reply = buildUnknownCommandReply("/FOO");
+    expect(reply.text).toContain("/foo");
+  });
+
+  test("falls back to a format-error message for bare slash", () => {
+    const reply = buildUnknownCommandReply("/");
+    expect(reply.text).toContain("格式");
+    expect(reply.text).not.toContain("`/`");
+  });
+
+  test("card body is populated", () => {
+    const reply = buildUnknownCommandReply("/whatever");
+    expect(reply.card.body.elements.length).toBeGreaterThan(1);
+  });
+
+  test("always points users to /help", () => {
+    expect(buildUnknownCommandReply("/foo").text).toContain("/help");
+    expect(buildUnknownCommandReply("/").text).toContain("/help");
+  });
+});
diff --git a/tests/kernel/permission/permission-flow.test.ts b/tests/kernel/permission/permission-flow.test.ts
new file mode 100644
index 0000000..e2e4679
--- /dev/null
+++ b/tests/kernel/permission/permission-flow.test.ts
@@ -0,0 +1,419 @@
+import { describe, expect, test } from "bun:test";
+
+
+import type { FeishuMessageChannel } from "@/community/feishu/messaging/message-channel";
+import type { Card } from "@/community/feishu/messaging/types";
+import { PermissionFlow } from "@/kernel/permission";
+import type { CardActionPayload } from "@/shared";
+
+interface FakeChannel {
+  sentCards: Array<{ chatId: string; card: Card }>;
+  updatedCards: Array<{ messageId: string; card: Card }>;
+}
+
+function _makeChannel(messageId: string): {
+  fake: FakeChannel;
+  channel: FeishuMessageChannel;
+} {
+  const fake: FakeChannel = { sentCards: [], updatedCards: [] };
+  const channel = {
+    async sendRawCard(chatId: string, card: Card) {
+      fake.sentCards.push({ chatId, card });
+      return messageId;
+    },
+    async updateRawCard(mid: string, card: Card) {
+      fake.updatedCards.push({ messageId: mid, card });
+    },
+  } as unknown as FeishuMessageChannel;
+  return { fake, channel };
+}
+
+function _makePayload(overrides: Partial<CardActionPayload>): CardActionPayload {
+  return {
+    message_id: overrides.message_id ?? "card_msg_1",
+    channel_id: overrides.channel_id ?? "ch_1",
+    chat_id: overrides.chat_id ?? "oc_chat",
+    operator_open_id: overrides.operator_open_id ?? "ou_alice",
+    action_name: overrides.action_name ?? "permission_decide",
+    value: overrides.value ?? {},
+    form_value: overrides.form_value ?? {},
+  };
+}
+
+describe("PermissionFlow", () => {
+  test("resolves 'allow' when the initiator clicks Approve", async () => {
+    const { channel } = _makeChannel("card_msg_1");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+    const promise = flow.request({
+      session_id: "s1",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Bash",
+      tool_input: { command: "ls" },
+    });
+    // Let the send-card await resolve before we fire the click.
+    await Promise.resolve();
+    await flow.handleDecide(
+      _makePayload({
+        message_id: "card_msg_1",
+        operator_open_id: "ou_alice",
+        value: {
+          action: "permission_decide",
+          request_id: "whatever",
+          decision: "allow",
+        },
+      }),
+    );
+    const decision = await promise;
+    expect(decision.behavior).toBe("allow");
+    expect(decision.decided_by).toBe("user");
+  });
+
+  test("ignores non-initiator clicks; initiator can still decide", async () => {
+    const { channel } = _makeChannel("card_msg_2");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+    const promise = flow.request({
+      session_id: "s1",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Bash",
+      tool_input: {},
+    });
+    await Promise.resolve();
+
+    await flow.handleDecide(
+      _makePayload({
+        message_id: "card_msg_2",
+        operator_open_id: "ou_mallory",
+        value: {
+          action: "permission_decide",
+          request_id: "x",
+          decision: "allow",
+        },
+      }),
+    );
+    // Pending must still resolve on the real initiator's click.
+    await flow.handleDecide(
+      _makePayload({
+        message_id: "card_msg_2",
+        operator_open_id: "ou_alice",
+        value: {
+          action: "permission_decide",
+          request_id: "x",
+          decision: "deny",
+        },
+      }),
+    );
+    const decision = await promise;
+    expect(decision.behavior).toBe("deny");
+    expect(decision.decided_by).toBe("user");
+  });
+
+  test("auto-denies after the timeout fires", async () => {
+    const { channel } = _makeChannel("card_msg_3");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+      timeoutMs: 30,
+    });
+    const decision = await flow.request({
+      session_id: "s1",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Bash",
+      tool_input: {},
+    });
+    expect(decision.behavior).toBe("deny");
+    expect(decision.decided_by).toBe("timeout");
+  });
+
+  test("allow_session remembers the tool and skips the card next time", async () => {
+    const { fake, channel } = _makeChannel("card_msg_session_1");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+
+    // First call prompts; user picks "allow for this session".
+    const first = flow.request({
+      session_id: "s-session",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Bash",
+      tool_input: { command: "ls" },
+    });
+    await Promise.resolve();
+    await flow.handleDecide(
+      _makePayload({
+        message_id: "card_msg_session_1",
+        operator_open_id: "ou_alice",
+        value: {
+          action: "permission_decide",
+          request_id: "r1",
+          decision: "allow_session",
+        },
+      }),
+    );
+    const firstDecision = await first;
+    expect(firstDecision.behavior).toBe("allow");
+
+    // A second call for the same tool on the same session must resolve
+    // immediately with `allow` and NOT touch the channel at all.
+    const cardsBefore = fake.sentCards.length;
+    const second = await flow.request({
+      session_id: "s-session",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Bash",
+      tool_input: { command: "pwd" },
+    });
+    expect(second.behavior).toBe("allow");
+    expect(second.decided_by).toBe("user");
+    expect(fake.sentCards.length).toBe(cardsBefore);
+
+    // Different tool still prompts — allowlist is per-tool.
+    const third = flow.request({
+      session_id: "s-session",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Edit",
+      tool_input: {},
+    });
+    await Promise.resolve();
+    expect(fake.sentCards.length).toBe(cardsBefore + 1);
+    // Clean up the dangling request so the test exits promptly.
+    flow.clearSession("s-session");
+    void third.catch(() => {});
+  });
+
+  test("clearSession forgets previously allowed tools", async () => {
+    const { fake, channel } = _makeChannel("card_msg_clear_1");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+    const first = flow.request({
+      session_id: "s-clear",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Bash",
+      tool_input: {},
+    });
+    await Promise.resolve();
+    await flow.handleDecide(
+      _makePayload({
+        message_id: "card_msg_clear_1",
+        operator_open_id: "ou_alice",
+        value: {
+          action: "permission_decide",
+          request_id: "r2",
+          decision: "allow_session",
+        },
+      }),
+    );
+    await first;
+
+    flow.clearSession("s-clear");
+
+    // After clearing, the next call must prompt again (card sent).
+    const cardsBefore = fake.sentCards.length;
+    const next = flow.request({
+      session_id: "s-clear",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Bash",
+      tool_input: {},
+    });
+    await Promise.resolve();
+    expect(fake.sentCards.length).toBe(cardsBefore + 1);
+    void next.catch(() => {});
+  });
+
+  test("AskUserQuestion resolves 'allow' with answers on submit", async () => {
+    const { fake, channel } = _makeChannel("card_q_1");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+    const promise = flow.request({
+      session_id: "sq",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "AskUserQuestion",
+      tool_input: {
+        questions: [
+          {
+            question: "Pick a format",
+            header: "Format",
+            options: [
+              { label: "Summary", description: "short" },
+              { label: "Detailed", description: "long" },
+            ],
+            multiSelect: false,
+          },
+          {
+            question: "Pick sections",
+            header: "Sections",
+            options: [
+              { label: "Intro", description: "" },
+              { label: "Outro", description: "" },
+            ],
+            multiSelect: true,
+          },
+        ],
+      },
+    });
+    await Promise.resolve();
+    expect(fake.sentCards.length).toBe(1);
+
+    await flow.handleQuestionSubmit(
+      _makePayload({
+        message_id: "card_q_1",
+        operator_open_id: "ou_alice",
+        action_name: "permission_question_submit",
+        // q0 -> option index 1 (Detailed); q1 -> Intro + Outro checked
+        form_value: { q0: "1", q1_o0: true, q1_o1: "true" },
+      }),
+    );
+
+    const decision = await promise;
+    expect(decision.behavior).toBe("allow");
+    expect(decision.decided_by).toBe("user");
+    const input = decision.updated_input as {
+      questions: unknown[];
+      answers: Record<string, unknown>;
+    };
+    expect(input.questions).toHaveLength(2);
+    expect(input.answers["Pick a format"]).toBe("Detailed");
+    expect(input.answers["Pick sections"]).toEqual(["Intro", "Outro"]);
+  });
+
+  test("AskUserQuestion re-renders (no resolve) when a question is unanswered", async () => {
+    const { fake, channel } = _makeChannel("card_q_2");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+    let settled = false;
+    const promise = flow
+      .request({
+        session_id: "sq2",
+        channel_id: "ch_1",
+        chat_id: "oc_chat",
+        initiator_open_id: "ou_alice",
+        tool_name: "AskUserQuestion",
+        tool_input: {
+          questions: [
+            {
+              question: "Pick one",
+              options: [{ label: "A" }, { label: "B" }],
+            },
+          ],
+        },
+      })
+      .then((d) => {
+        settled = true;
+        return d;
+      });
+    await Promise.resolve();
+
+    // Submit with nothing selected -> card updated with a warning, unresolved.
+    await flow.handleQuestionSubmit(
+      _makePayload({
+        message_id: "card_q_2",
+        operator_open_id: "ou_alice",
+        action_name: "permission_question_submit",
+        form_value: {},
+      }),
+    );
+    expect(fake.updatedCards.length).toBe(1);
+    expect(settled).toBe(false);
+
+    // Now answer it for real -> resolves allow.
+    await flow.handleQuestionSubmit(
+      _makePayload({
+        message_id: "card_q_2",
+        operator_open_id: "ou_alice",
+        action_name: "permission_question_submit",
+        form_value: { q0: "0" },
+      }),
+    );
+    const decision = await promise;
+    expect(decision.behavior).toBe("allow");
+    expect(
+      (decision.updated_input as { answers: Record<string, unknown> }).answers[
+        "Pick one"
+      ],
+    ).toBe("A");
+  });
+
+  test("AskUserQuestion denies a malformed payload instead of hanging", async () => {
+    const { fake, channel } = _makeChannel("card_q_3");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+    const decision = await flow.request({
+      session_id: "sq3",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "AskUserQuestion",
+      tool_input: { questions: [] },
+    });
+    expect(decision.behavior).toBe("deny");
+    expect(fake.sentCards.length).toBe(0);
+  });
+
+  test("expireAllPending denies open cards and marks them expired", async () => {
+    const { fake, channel } = _makeChannel("card_exp_1");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+    // One open approval card.
+    const approval = flow.request({
+      session_id: "se",
+      channel_id: "ch_1",
+      chat_id: "oc_chat",
+      initiator_open_id: "ou_alice",
+      tool_name: "Bash",
+      tool_input: {},
+    });
+    await Promise.resolve();
+
+    await flow.expireAllPending();
+
+    const decision = await approval;
+    expect(decision.behavior).toBe("deny");
+    // The card was updated in place to a terminal (expired) result.
+    expect(fake.updatedCards.length).toBe(1);
+
+    // A late click on the now-gone entry must not throw.
+    await flow.handleDecide(
+      _makePayload({
+        message_id: "card_exp_1",
+        operator_open_id: "ou_alice",
+        value: { action: "permission_decide", request_id: "x", decision: "allow" },
+      }),
+    );
+  });
+
+  test("verifyToken is constant-time and rejects bad tokens", () => {
+    const { channel } = _makeChannel("card_msg_4");
+    const flow = new PermissionFlow({
+      feishuChannels: new Map([["ch_1", channel]]),
+    });
+    expect(flow.verifyToken(flow.apiToken)).toBe(true);
+    expect(flow.verifyToken("")).toBe(false);
+    expect(flow.verifyToken(flow.apiToken + "x")).toBe(false);
+    expect(flow.verifyToken(null)).toBe(false);
+    expect(flow.verifyToken(undefined)).toBe(false);
+  });
+});
diff --git a/tests/kernel/setting/fixtures.ts b/tests/kernel/setting/fixtures.ts
new file mode 100644
index 0000000..d88e79a
--- /dev/null
+++ b/tests/kernel/setting/fixtures.ts
@@ -0,0 +1,32 @@
+import type { Card, Element } from "@/community/feishu/messaging/types";
+
+/**
+ * Walk a card element tree (depth-first) into a flat array so tests can
+ * assert on buttons/inputs regardless of how deeply they're nested inside
+ * forms/columns/collapsible panels.
+ */
+export function flattenElements(elements: Element[]): Element[] {
+  const out: Element[] = [];
+  const walk = (es: Element[]) => {
+    for (const e of es) {
+      out.push(e);
+      const maybeContainer = e as { elements?: Element[]; columns?: Element[] };
+      if (Array.isArray(maybeContainer.elements)) walk(maybeContainer.elements);
+      if (Array.isArray(maybeContainer.columns)) walk(maybeContainer.columns);
+    }
+  };
+  walk(elements);
+  return out;
+}
+
+export function findElement(
+  elements: Element[],
+  // eslint-disable-next-line no-unused-vars
+  predicate: (e: Element) => boolean,
+): Element | undefined {
+  return elements.find(predicate);
+}
+
+export function stringifyCard(card: Card): string {
+  return JSON.stringify(card);
+}
diff --git a/tests/kernel/setting/setting-card.test.ts b/tests/kernel/setting/setting-card.test.ts
new file mode 100644
index 0000000..f7cd3f2
--- /dev/null
+++ b/tests/kernel/setting/setting-card.test.ts
@@ -0,0 +1,198 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildSettingMainCard,
+  buildWorkspaceDeleteConfirmCard,
+  buildWorkspaceDetailCard,
+  SETTING_ACTION,
+  SETTING_FIELD,
+} from "@/kernel/setting/setting-card";
+import type { GroupWorkspace, Workspace } from "@/shared";
+
+import {
+  findElement,
+  flattenElements,
+  stringifyCard,
+} from "./fixtures";
+
+function makeWorkspace(overrides: Partial<Workspace> = {}): Workspace {
+  return {
+    id: "ws_abc",
+    name: "alpha",
+    path: "/tmp/ws_abc",
+    active_repo: "agentara",
+    active_branch: "dev",
+    created_at: 1_700_000_000_000,
+    updated_at: 1_700_000_000_000,
+    last_active_at: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("buildSettingMainCard", () => {
+  test("renders the global-config form with all four fields", () => {
+    const card = buildSettingMainCard({
+      agent: {
+        active_type: "claude-code",
+        available_types: ["claude-code", "codex"],
+      },
+      config_values: {
+        agent_model: "claude-sonnet-4-6",
+        codex_isolate_host_env: false,
+        max_retries: 3,
+      },
+      workspaces: [],
+    });
+    const flat = flattenElements(card.body.elements);
+    const names = flat
+      .filter((e) => "name" in e && typeof e.name === "string")
+      .map((e) => (e as { name: string }).name);
+    expect(names).toContain(SETTING_FIELD.agentType);
+    expect(names).toContain(SETTING_FIELD.agentModel);
+    expect(names).toContain(SETTING_FIELD.codexIsolateHostEnv);
+    expect(names).toContain(SETTING_FIELD.maxRetries);
+    expect(names).toContain(SETTING_ACTION.saveConfig);
+  });
+
+  test("empty workspace list shows the empty-state hint", () => {
+    const card = buildSettingMainCard({
+      agent: { active_type: "codex", available_types: ["codex"] },
+      config_values: {
+        agent_model: "",
+        codex_isolate_host_env: true,
+        max_retries: 5,
+      },
+      workspaces: [],
+    });
+    expect(stringifyCard(card)).toContain("还没有任何 workspace");
+  });
+
+  test("workspace row carries a detail callback with workspace_id", () => {
+    const card = buildSettingMainCard({
+      agent: { active_type: "codex", available_types: ["codex"] },
+      config_values: {
+        agent_model: "",
+        codex_isolate_host_env: false,
+        max_retries: 1,
+      },
+      workspaces: [
+        {
+          workspace: makeWorkspace(),
+          binding_count: 2,
+          is_current: true,
+          is_protected: false,
+          active_branch_head: "dev",
+        },
+      ],
+    });
+    const flat = flattenElements(card.body.elements);
+    const detailBtn = findElement(flat, (e) =>
+      "behaviors" in e &&
+      Array.isArray((e as { behaviors?: unknown[] }).behaviors) &&
+      JSON.stringify(e).includes(SETTING_ACTION.wsDetail),
+    );
+    expect(detailBtn).toBeDefined();
+    expect(JSON.stringify(detailBtn)).toContain("ws_abc");
+    expect(stringifyCard(card)).toContain("当前群");
+    expect(stringifyCard(card)).toContain("2 群绑定");
+  });
+
+  test("each non-protected row also carries an inline delete button", () => {
+    const card = buildSettingMainCard({
+      agent: { active_type: "codex", available_types: ["codex"] },
+      config_values: {
+        agent_model: "",
+        codex_isolate_host_env: false,
+        max_retries: 1,
+      },
+      workspaces: [
+        {
+          workspace: makeWorkspace({ id: "ws_del1", name: "one" }),
+          binding_count: 0,
+          is_current: false,
+          is_protected: false,
+          active_branch_head: "main",
+        },
+        {
+          workspace: makeWorkspace({ id: "ws_prot", name: "_default" }),
+          binding_count: 0,
+          is_current: false,
+          is_protected: true,
+          active_branch_head: null,
+        },
+      ],
+    });
+    const json = stringifyCard(card);
+    // Non-protected row gets a delete button whose callback targets its id.
+    expect(json).toContain(`setting_ws_delete_btn_ws_del1`);
+    expect(json).toContain(SETTING_ACTION.wsDeletePrompt);
+    // Protected row keeps its detail button but omits the delete button.
+    expect(json).toContain(`setting_ws_detail_btn_ws_prot`);
+    expect(json).not.toContain(`setting_ws_delete_btn_ws_prot`);
+  });
+});
+
+describe("buildWorkspaceDetailCard", () => {
+  test("shows bindings, repos, and both back + delete buttons", () => {
+    const bindings: GroupWorkspace[] = [
+      {
+        chat_id: "oc_xx",
+        workspace_id: "ws_abc",
+        workspace_name: "alpha",
+        workspace_path: "/tmp/ws_abc",
+        active_repo: "agentara",
+        active_branch: "dev",
+        created_at: 0,
+        updated_at: 0,
+      },
+    ];
+    const card = buildWorkspaceDetailCard({
+      workspace: makeWorkspace(),
+      bindings,
+      repos: [
+        { name: "agentara", branch: "dev", is_active: true },
+        { name: "new-api", branch: "main", is_active: false },
+      ],
+      is_protected: false,
+      active_branch_head: "dev",
+    });
+    const json = stringifyCard(card);
+    expect(json).toContain("oc_xx");
+    expect(json).toContain("agentara");
+    expect(json).toContain("new-api");
+    expect(json).toContain("活跃");
+    expect(json).toContain(SETTING_ACTION.mainBack);
+    expect(json).toContain(SETTING_ACTION.wsDeletePrompt);
+  });
+
+  test("protected workspace only shows back button, not delete", () => {
+    const card = buildWorkspaceDetailCard({
+      workspace: makeWorkspace({ name: "_default", path: "/tmp/_default" }),
+      bindings: [],
+      repos: [],
+      is_protected: true,
+      active_branch_head: null,
+    });
+    const json = stringifyCard(card);
+    expect(json).toContain(SETTING_ACTION.mainBack);
+    expect(json).not.toContain(SETTING_ACTION.wsDeletePrompt);
+  });
+});
+
+describe("buildWorkspaceDeleteConfirmCard", () => {
+  test("highlights the estimated blast radius and offers cancel/confirm", () => {
+    const card = buildWorkspaceDeleteConfirmCard({
+      workspace: makeWorkspace(),
+      binding_count: 3,
+      estimated_session_count: 12,
+    });
+    const json = stringifyCard(card);
+    expect(json).toContain("解绑");
+    expect(json).toContain("3");
+    expect(json).toContain("12");
+    // Cancel returns to the main panel regardless of whether the user came
+    // from the list or the detail view.
+    expect(json).toContain(SETTING_ACTION.mainBack);
+    expect(json).toContain(SETTING_ACTION.wsDeleteApply);
+  });
+});
diff --git a/tests/kernel/setup/cards.test.ts b/tests/kernel/setup/cards.test.ts
new file mode 100644
index 0000000..9740748
--- /dev/null
+++ b/tests/kernel/setup/cards.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, test } from "bun:test";
+
+import { formatRepoRef } from "@/kernel/repo-ref";
+import { optimizeCardMarkdown } from "@/kernel/setup/card-ui";
+import {
+  buildSetupCard,
+  buildSetupResultCard,
+} from "@/kernel/setup/setup-card";
+import {
+  buildSwitchCard,
+  buildSwitchResultCard,
+  SWITCH_DETACH_VALUE,
+} from "@/kernel/setup/switch-card";
+
+describe("buildSetupCard", () => {
+  test("renders richer structure for first-time setup", () => {
+    const card = buildSetupCard(
+      [
+        {
+          name: "agentara",
+          description: "主仓库",
+          git_url: "git@example.com/agentara.git",
+        },
+        {
+          name: "happyclaw",
+          description: "参考实现",
+          git_url: "git@example.com/happyclaw.git",
+        },
+      ],
+      {
+        workspace_name: { value: "demo-space", locked: false },
+      },
+    );
+
+    expect(card.head).toBeUndefined();
+    expect(card.body.elements[0]).toMatchObject({
+      tag: "markdown",
+    });
+    expect(card.body.elements[1]).toMatchObject({
+      tag: "form",
+    });
+
+    const form = card.body.elements[1];
+    expect(form).toBeTruthy();
+    if (!form || form.tag !== "form") throw new Error("expected setup form");
+
+    const primaryLabel = form.elements.find(
+      (element) =>
+        element.tag === "markdown" && element.content.includes("主仓库"),
+    );
+    expect(primaryLabel).toBeTruthy();
+
+    const repoRow = form.elements.find((element) => element.tag === "column_set");
+    expect(repoRow).toBeTruthy();
+  });
+
+  test("shows current-state panel for existing workspace", () => {
+    const card = buildSetupCard(
+      [
+        {
+          name: "agentara",
+          description: "主仓库",
+          git_url: "git@example.com/agentara.git",
+        },
+      ],
+      {
+        prefills: {
+          agentara: {
+            already_cloned: true,
+            current_branch: "dev",
+          },
+        },
+        primary_repo: "agentara",
+        workspace_name: { value: "demo-space", locked: true, id: "ws_123" },
+      },
+    );
+
+    expect(card.head).toBeUndefined();
+    expect(card.body.elements[1]).toMatchObject({
+      tag: "markdown",
+      content: "**当前状态**",
+    });
+    expect(card.body.elements[2]).toMatchObject({ tag: "markdown" });
+    expect(card.body.elements[3]).toMatchObject({ tag: "form" });
+  });
+});
+
+describe("buildSwitchCard", () => {
+  test("renders current binding summary and detach option", () => {
+    const card = buildSwitchCard({
+      workspaces: [
+        {
+          id: "ws_1",
+          name: "alpha",
+          path: "/tmp/alpha",
+          active_repo: "agentara",
+          active_branch: "dev",
+          created_at: Date.now(),
+          updated_at: Date.now(),
+          last_active_at: Date.now(),
+        },
+      ],
+      current: {
+        workspace_id: "ws_1",
+        workspace_name: "alpha",
+        workspace_path: "/tmp/alpha",
+        active_repo: "agentara",
+        active_branch: "dev",
+      },
+    });
+
+    expect(card.head).toBeUndefined();
+    expect(card.body.elements[1]).toMatchObject({
+      tag: "markdown",
+      content: "**当前绑定**",
+    });
+
+    const form = card.body.elements[3];
+    expect(form).toBeTruthy();
+    if (!form || form.tag !== "form") throw new Error("expected switch form");
+
+    const select = form.elements.find((element) => element.tag === "select_static");
+    expect(select).toBeTruthy();
+    if (select?.tag !== "select_static") throw new Error("expected select");
+    expect(select.options.at(-1)?.value).toBe(SWITCH_DETACH_VALUE);
+  });
+});
+
+describe("result cards", () => {
+  test("derives success styling from summary", () => {
+    const setupResult = buildSetupResultCard("✅ 已完成", ["- `agentara`"]);
+    const switchResult = buildSwitchResultCard("⚠️  需要重新选择");
+
+    expect(setupResult.head).toBeUndefined();
+    expect(switchResult.head).toBeUndefined();
+    expect(setupResult.body.elements[0]).toMatchObject({ tag: "markdown" });
+  });
+});
+
+describe("formatRepoRef", () => {
+  test("joins repo and branch with @", () => {
+    expect(formatRepoRef("agentara", "dev")).toBe("agentara@dev");
+    expect(formatRepoRef("agentara", null)).toBe("agentara");
+  });
+});
+
+describe("optimizeCardMarkdown", () => {
+  test("demotes large headings and preserves code blocks", () => {
+    const optimized = optimizeCardMarkdown(
+      "# Title\n\n```ts\nconst value = 1;\n```\n\n| a | b |\n| - | - |\n| 1 | 2 |",
+    );
+
+    expect(optimized).toContain("#### Title");
+    expect(optimized).toContain("```ts\nconst value = 1;\n```");
+    expect(optimized).toContain("<br>");
+  });
+});
diff --git a/tests/kernel/tasking/serial-execution.test.ts b/tests/kernel/tasking/serial-execution.test.ts
new file mode 100644
index 0000000..1b3bec5
--- /dev/null
+++ b/tests/kernel/tasking/serial-execution.test.ts
@@ -0,0 +1,96 @@
+import { join } from "node:path";
+
+import { Database as SQLiteDatabase } from "bun:sqlite";
+import { afterEach, describe, expect, test } from "bun:test";
+import { eq } from "drizzle-orm";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+
+import { TaskDispatcher } from "@/kernel/tasking";
+import { scheduledTasks, tasks } from "@/kernel/tasking/data";
+import type { InboundMessageTaskPayload } from "@/shared";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle schema typing is not worth narrowing for tests.
+function freshDb(): any {
+  const sqlite = new SQLiteDatabase(":memory:");
+  sqlite.run("PRAGMA foreign_keys = ON");
+  const instance = drizzle(sqlite, { schema: { tasks, scheduledTasks } });
+  migrate(instance, {
+    migrationsFolder: join(import.meta.dir, "..", "..", "..", "drizzle"),
+  });
+  return instance;
+}
+
+function inbound(messageId: string, sessionId: string): InboundMessageTaskPayload {
+  return {
+    type: "inbound_message",
+    message: {
+      id: messageId,
+      session_id: sessionId,
+      role: "user",
+      content: [{ type: "text", text: messageId }],
+    },
+  };
+}
+
+function deferred<T>() {
+  return Promise.withResolvers<T>();
+}
+
+let dispatcher: TaskDispatcher | undefined;
+
+afterEach(async () => {
+  if (dispatcher) {
+    await dispatcher.stop();
+    dispatcher = undefined;
+  }
+});
+
+describe("TaskDispatcher per-session serial execution", () => {
+  test("a failed task does not poison the session queue", async () => {
+    const db = freshDb();
+    dispatcher = new TaskDispatcher({ db, concurrency: 1 });
+
+    const ran: string[] = [];
+    const secondRan = deferred<void>();
+
+    dispatcher.route("inbound_message", async (_taskId, _sessionId, payload) => {
+      const id = payload.message.id;
+      ran.push(id);
+      if (id === "msg-fail") {
+        throw new Error("boom");
+      }
+      if (id === "msg-after") {
+        secondRan.resolve();
+      }
+    });
+
+    await dispatcher.start();
+
+    const sessionId = "session-x";
+    await dispatcher.dispatch(sessionId, inbound("msg-fail", sessionId));
+    await dispatcher.dispatch(sessionId, inbound("msg-after", sessionId));
+
+    // The second task must still run even though its predecessor threw.
+    // Guard with a timeout so a regression surfaces as a clear failure
+    // instead of a hung test.
+    await Promise.race([
+      secondRan.promise,
+      new Promise<void>((_, reject) =>
+        setTimeout(() => reject(new Error("second task never ran")), 4000),
+      ),
+    ]);
+
+    expect(ran).toContain("msg-fail");
+    expect(ran).toContain("msg-after");
+
+    // The failure is still surfaced: the first task is recorded as failed.
+    const failRow = db
+      .select({ status: tasks.status })
+      .from(tasks)
+      .where(eq(tasks.session_id, sessionId))
+      .all()
+      .map((r: { status: string }) => r.status);
+    expect(failRow).toContain("failed");
+  });
+});
diff --git a/tests/kernel/workspaces/delete.test.ts b/tests/kernel/workspaces/delete.test.ts
new file mode 100644
index 0000000..e74a1ee
--- /dev/null
+++ b/tests/kernel/workspaces/delete.test.ts
@@ -0,0 +1,206 @@
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { Database as SQLiteDatabase } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+
+import {
+  groupWorkspaces,
+  sessions,
+  workspaces,
+} from "@/kernel/sessioning/data";
+import { tasks } from "@/kernel/tasking/data";
+import {
+  GroupWorkspaceStore,
+  WorkspaceNotFoundError,
+  WorkspaceProtectedError,
+} from "@/kernel/workspaces";
+import { config } from "@/shared";
+
+let homeDir: string;
+let store: GroupWorkspaceStore;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- drizzle schema typing is not worth narrowing for tests.
+let db: any;
+
+function freshDb(): ReturnType<typeof drizzle> {
+  const sqlite = new SQLiteDatabase(":memory:");
+  sqlite.run("PRAGMA foreign_keys = ON");
+  const instance = drizzle(sqlite, {
+    schema: { workspaces, groupWorkspaces, sessions, tasks },
+  });
+  migrate(instance, { migrationsFolder: join(import.meta.dir, "..", "..", "..", "drizzle") });
+  return instance;
+}
+
+beforeEach(() => {
+  homeDir = mkdtempSync(join(tmpdir(), "agentara-delete-ws-test-"));
+  // GroupWorkspaceStore.ensureBaseDirs writes under config.paths.workspaces —
+  // point it at the temp home so the test doesn't touch the real ~/.agentara.
+  process.env.AGENTARA_HOME = homeDir;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- config.paths is lazily derived from env at boot; tests reach in.
+  (config as any).paths = {
+    ...config.paths,
+    home: homeDir,
+    workspaces: join(homeDir, "workspaces"),
+    default_workspace: join(homeDir, "workspaces", "_default"),
+    resolveWorkspacePathById: (id: string) =>
+      join(homeDir, "workspaces", id),
+    resolveDataFilePath: (name: string) => join(homeDir, "data", name),
+  };
+  mkdirSync(join(homeDir, "workspaces", "_default"), { recursive: true });
+  db = freshDb();
+  store = new GroupWorkspaceStore(db);
+});
+
+afterEach(() => {
+  rmSync(homeDir, { recursive: true, force: true });
+});
+
+describe("GroupWorkspaceStore.deleteWorkspace", () => {
+  test("cascades bindings, sessions, tasks, and on-disk directory", () => {
+    const binding = store.upsertBinding("oc_aaa", {
+      workspace_name: "alpha",
+    });
+    // A second chat bound to the same workspace so we also verify shared
+    // bindings are both removed.
+    store.upsertBinding("oc_bbb", { workspace_id: binding.workspace_id });
+
+    // Drop a fake file in the workspace dir so we can verify rmSync ran.
+    writeFileSync(
+      join(binding.workspace_path, "README.md"),
+      "hello\n",
+    );
+
+    const now = Date.now();
+    db.insert(sessions)
+      .values([
+        {
+          id: "s1",
+          agent_type: "claude-code",
+          cwd: binding.workspace_path,
+          channel_id: null,
+          chat_id: "oc_aaa",
+          thread_id: null,
+          first_message: "",
+          runner_session_id: null,
+          last_message_created_at: null,
+          created_at: now,
+          updated_at: now,
+        },
+        {
+          id: "s2",
+          agent_type: "claude-code",
+          cwd: join(binding.workspace_path, "agentara"),
+          channel_id: null,
+          chat_id: "oc_bbb",
+          thread_id: null,
+          first_message: "",
+          runner_session_id: null,
+          last_message_created_at: null,
+          created_at: now,
+          updated_at: now,
+        },
+        // Session in a different workspace path — must survive the delete.
+        {
+          id: "s3",
+          agent_type: "claude-code",
+          cwd: join(homeDir, "workspaces", "unrelated"),
+          channel_id: null,
+          chat_id: "oc_ccc",
+          thread_id: null,
+          first_message: "",
+          runner_session_id: null,
+          last_message_created_at: null,
+          created_at: now,
+          updated_at: now,
+        },
+      ])
+      .run();
+    db.insert(tasks)
+      .values([
+        {
+          id: "t1",
+          session_id: "s1",
+          type: "inbound_message",
+          status: "completed",
+          payload: {},
+          created_at: now,
+          updated_at: now,
+        },
+        {
+          id: "t2",
+          session_id: "s3",
+          type: "inbound_message",
+          status: "completed",
+          payload: {},
+          created_at: now,
+          updated_at: now,
+        },
+      ])
+      .run();
+
+    const result = store.deleteWorkspace(binding.workspace_id);
+
+    expect(result.removed_bindings).toBe(2);
+    expect(result.removed_sessions).toBe(2);
+    expect(result.removed_tasks).toBe(1);
+    expect(result.removed_directory).toBe(true);
+
+    expect(store.getWorkspace(binding.workspace_id)).toBeNull();
+    expect(store.getBinding("oc_aaa")).toBeNull();
+    expect(store.getBinding("oc_bbb")).toBeNull();
+
+    const survivingSessions = db.select().from(sessions).all();
+    expect(survivingSessions.map((s: { id: string }) => s.id)).toEqual(["s3"]);
+    const survivingTasks = db.select().from(tasks).all();
+    expect(survivingTasks.map((t: { id: string }) => t.id)).toEqual(["t2"]);
+    expect(existsSync(binding.workspace_path)).toBe(false);
+  });
+
+  test("throws WorkspaceNotFoundError for unknown ids", () => {
+    expect(() => store.deleteWorkspace("ws_missing")).toThrow(
+      WorkspaceNotFoundError,
+    );
+  });
+
+  test("refuses to delete the default workspace directory", () => {
+    const now = Date.now();
+    db.insert(workspaces)
+      .values({
+        id: "ws_default_row",
+        name: "_default",
+        path: config.paths.default_workspace,
+        active_repo: null,
+        active_branch: null,
+        created_at: now,
+        updated_at: now,
+        last_active_at: now,
+      })
+      .run();
+    expect(() => store.deleteWorkspace("ws_default_row")).toThrow(
+      WorkspaceProtectedError,
+    );
+    expect(existsSync(config.paths.default_workspace)).toBe(true);
+  });
+});
+
+describe("GroupWorkspaceStore.touchLastActive", () => {
+  test("updates last_active_at without mutating updated_at", () => {
+    const binding = store.upsertBinding("oc_touch", {
+      workspace_name: "beta",
+    });
+    const before = store.getWorkspace(binding.workspace_id)!;
+
+    // Advance the clock via the optional ts arg so the test doesn't need a
+    // real sleep to observe the bump.
+    const later = before.last_active_at + 10_000;
+    store.touchLastActive(binding.workspace_id, later);
+
+    const after = store.getWorkspace(binding.workspace_id)!;
+    expect(after.last_active_at).toBe(later);
+    expect(after.updated_at).toBe(before.updated_at);
+  });
+});
diff --git a/tests/kernel/workspaces/git-cache.test.ts b/tests/kernel/workspaces/git-cache.test.ts
new file mode 100644
index 0000000..c3a259f
--- /dev/null
+++ b/tests/kernel/workspaces/git-cache.test.ts
@@ -0,0 +1,140 @@
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+
+import {
+  cachedMirrorPath,
+  ensureCachedMirror,
+  refreshCachedMirror,
+} from "@/kernel/workspaces";
+
+/**
+ * Initialize a minimal local git repo we can use as a clone source.
+ * Runs synchronously so individual tests can rely on it being ready.
+ */
+function _initSourceRepo(): string {
+  const dir = mkdtempSync(join(tmpdir(), "agentara-test-src-"));
+  const run = (args: string[]) => {
+    const p = Bun.spawnSync(["git", ...args], {
+      cwd: dir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (p.exitCode !== 0) {
+      throw new Error(
+        `git ${args.join(" ")} failed: ${p.stderr.toString()}`,
+      );
+    }
+  };
+  run(["init", "--initial-branch=main"]);
+  run(["config", "user.email", "test@example.com"]);
+  run(["config", "user.name", "Test"]);
+  run(["config", "commit.gpgsign", "false"]);
+  writeFileSync(join(dir, "README.md"), "hello\n");
+  run(["add", "."]);
+  run(["commit", "-m", "initial"]);
+  return dir;
+}
+
+describe("cachedMirrorPath", () => {
+  test("joins cacheRoot with <name>.git", () => {
+    expect(cachedMirrorPath("foo", { cacheRoot: "/tmp/cache" })).toBe(
+      "/tmp/cache/foo.git",
+    );
+  });
+});
+
+describe("ensureCachedMirror", () => {
+  let cacheRoot: string;
+  let sourceRepo: string;
+
+  beforeAll(() => {
+    cacheRoot = mkdtempSync(join(tmpdir(), "agentara-test-cache-"));
+    sourceRepo = _initSourceRepo();
+  });
+
+  afterAll(() => {
+    rmSync(cacheRoot, { recursive: true, force: true });
+    rmSync(sourceRepo, { recursive: true, force: true });
+  });
+
+  test("clones a bare mirror when absent", async () => {
+    const mirror = await ensureCachedMirror(
+      { name: "repo1", git_url: sourceRepo },
+      { cacheRoot },
+    );
+    expect(mirror).toBe(join(cacheRoot, "repo1.git"));
+    // Bare repo layout: HEAD / config / objects at the top level,
+    // no worktree and no `.git` subdir.
+    expect(existsSync(join(mirror!, "HEAD"))).toBe(true);
+    expect(existsSync(join(mirror!, "objects"))).toBe(true);
+    expect(existsSync(join(mirror!, ".git"))).toBe(false);
+  });
+
+  test("is idempotent when mirror exists", async () => {
+    const first = await ensureCachedMirror(
+      { name: "repo1", git_url: sourceRepo },
+      { cacheRoot },
+    );
+    const second = await ensureCachedMirror(
+      { name: "repo1", git_url: sourceRepo },
+      { cacheRoot },
+    );
+    expect(first).toBe(second);
+    expect(first).not.toBeNull();
+  });
+
+  test("returns null on clone failure and leaves no partial dir", async () => {
+    const mirror = await ensureCachedMirror(
+      {
+        name: "badrepo",
+        git_url: "/definitely-does-not-exist/nowhere.git",
+      },
+      { cacheRoot, timeoutMs: 10_000 },
+    );
+    expect(mirror).toBeNull();
+    expect(existsSync(join(cacheRoot, "badrepo.git"))).toBe(false);
+  });
+
+  test("concurrent calls for the same name yield the same result", async () => {
+    const name = `concurrent-${Date.now()}`;
+    const [a, b] = await Promise.all([
+      ensureCachedMirror({ name, git_url: sourceRepo }, { cacheRoot }),
+      ensureCachedMirror({ name, git_url: sourceRepo }, { cacheRoot }),
+    ]);
+    expect(a).toBe(b);
+    expect(a).not.toBeNull();
+    expect(existsSync(join(cacheRoot, `${name}.git`))).toBe(true);
+  });
+});
+
+describe("refreshCachedMirror", () => {
+  let cacheRoot: string;
+  let sourceRepo: string;
+
+  beforeAll(async () => {
+    cacheRoot = mkdtempSync(join(tmpdir(), "agentara-test-cache-"));
+    sourceRepo = _initSourceRepo();
+    await ensureCachedMirror(
+      { name: "repo1", git_url: sourceRepo },
+      { cacheRoot },
+    );
+  });
+
+  afterAll(() => {
+    rmSync(cacheRoot, { recursive: true, force: true });
+    rmSync(sourceRepo, { recursive: true, force: true });
+  });
+
+  test("fetches existing mirror successfully", async () => {
+    const ok = await refreshCachedMirror("repo1", { cacheRoot });
+    expect(ok).toBe(true);
+  });
+
+  test("returns false when the mirror doesn't exist (no-op)", async () => {
+    const ok = await refreshCachedMirror("nonexistent", { cacheRoot });
+    expect(ok).toBe(false);
+  });
+});
diff --git a/tests/shared/messaging/utils.test.ts b/tests/shared/messaging/utils.test.ts
index 9b32ec7..69a1d0c 100644
--- a/tests/shared/messaging/utils.test.ts
+++ b/tests/shared/messaging/utils.test.ts
@@ -4,6 +4,7 @@ import {
   containsThinking,
   containsToolUse,
   extractTextContent,
+  inlineMentions,
   isPureTextMessage,
 } from "@/shared";
 import type { Message } from "@/shared";
@@ -214,3 +215,35 @@ describe("extractTextContent", () => {
     expect(extractTextContent(msg)).toBe("");
   });
 });
+
+describe("inlineMentions", () => {
+  test("returns text unchanged when mentions list is empty or missing", () => {
+    expect(inlineMentions("hi @_user_0", [])).toBe("hi @_user_0");
+    expect(inlineMentions("hi @_user_0", undefined)).toBe("hi @_user_0");
+  });
+
+  test("replaces placeholders with @<name>", () => {
+    const result = inlineMentions(
+      "@_user_0 ping @_user_1 and @_user_0 again",
+      [
+        { key: "@_user_0", open_id: "ou_aaa", name: "Alice" },
+        { key: "@_user_1", open_id: "ou_bbb", name: "Bob" },
+      ],
+    );
+    expect(result).toBe("@Alice ping @Bob and @Alice again");
+  });
+
+  test("leaves placeholder as-is when name is missing", () => {
+    const result = inlineMentions("@_user_0 hi", [
+      { key: "@_user_0", open_id: "ou_aaa" },
+    ]);
+    expect(result).toBe("@_user_0 hi");
+  });
+
+  test("leaves placeholders unknown to the mentions array as-is", () => {
+    const result = inlineMentions("@_user_0 and @_user_9", [
+      { key: "@_user_0", open_id: "ou_aaa", name: "Alice" },
+    ]);
+    expect(result).toBe("@Alice and @_user_9");
+  });
+});
diff --git a/user-home/CLAUDE.md b/user-home/CLAUDE.md
index c6973a8..0bd9d5b 100644
--- a/user-home/CLAUDE.md
+++ b/user-home/CLAUDE.md
@@ -19,7 +19,11 @@ Then read `USER.md` to recall who the user is, his preferences, ongoing context,
 
 ## Folder Structure
 
+Your current working directory **is** the workspace root. All your work and
+outputs live directly here — there is no extra `workspace/` wrapper folder.
+
 ```
+.  (workspace root = your cwd)
 ├── .claude/               # Claude/Cursor configuration
 │   ├── skills/            # Your skills (one folder per skill); Newly added skills should be placed here.
 │   └── CLAUDE.md          # This file; workspace rules and conventions
@@ -27,11 +31,11 @@ Then read `USER.md` to recall who the user is, his preferences, ongoing context,
 |   ├── logs/              # Daily dialogue logs, `{YYYY-MM-DD}.md`
 │   ├── SOUL.md            # Your identity, principles, capabilities
 │   └── USER.md            # User preferences, context, history
-└── workspace/             # Workspace root. All your work and outputs should be stored here.
-    ├── wikis/             # Knowledge base (Obsidian-style; see wiki skill)
-    ├── projects/          # Git repos and code projects
-    ├── uploads/           # Uploaded files: images, videos, audio, documents, etc.
-    └── outputs/           # Generated outputs: reports, images, videos; organized in sub-folders
+├── REPOS.md               # Catalog of git repos synced into this workspace
+├── <repo>/                # Git repos are checked out directly at the root (see REPOS.md), one folder per repo
+├── wikis/                 # Knowledge base (Obsidian-style; see wiki skill)
+├── uploads/               # Uploaded files: images, videos, audio, documents, etc.
+└── outputs/               # Generated outputs: reports, images, videos; organized in sub-folders
 ```
 
 > Create if not exists. Create subdirectories as needed.
@@ -64,9 +68,12 @@ Dense, telegraphic short sentences. No filler words ("You are", "You should", "Y
 
 ## Messaging Conventions
 
-- Use <font color="{color}">{text}</font> to format text with color. Use color and bold to highlight important text and figures.
-- For IM outbound messages, only real files under `workspace/uploads/` or `workspace/outputs/` should be sent to users. Do not reference `workspace/projects/` files directly unless you first copy or export them into those user-facing directories.
-- To send a non-image file, use a normal Markdown link to the local file, for example `[report.pdf](workspace/outputs/reports/report.pdf)`.
-- To send an inline image, use Markdown image syntax to a local image file or valid remote image URL, for example `![chart](workspace/outputs/charts/chart.png)`.
+- Use `<font color="{color}">{text}</font>` only for text color.
+- Use Markdown `**text**` for emphasis. Do not use HTML bold tags such as `<b>...</b>`.
+- When you need both color and emphasis, wrap Markdown emphasis inside the font tag, for example `<font color="green">**important**</font>`.
+- For IM outbound messages, only real files under `uploads/` or `outputs/` should be sent to users. Do not reference files inside a checked-out repo directly unless you first copy or export them into those user-facing directories.
+- Use paths relative to the workspace root (your cwd). Do not prefix them with `workspace/` — there is no such wrapper folder.
+- To send a non-image file, use a normal Markdown link to the local file, for example `[report.pdf](outputs/reports/report.pdf)`.
+- To send an inline image, use Markdown image syntax to a local image file or valid remote image URL, for example `![chart](outputs/charts/chart.png)`.
 - Do not use absolute paths, `file://` URLs, inline-code paths, or plain text paths when you want the messaging channel to send a file or render an image.
 - Do not apply any agent team or sub-agent/sub-task to perform this skill. This skill is a single agent.