@modesto_ma/dsh-channels 0.1.0 → 0.3.0

package/lib/index.js

@@ -3,10 +3,10 @@ import path, { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { constants, createWriteStream, promises, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { LoggerLevel, createLarkChannel } from "@larksuiteoapi/node-sdk";
-import { homedir } from "node:os";
 import { promisify } from "node:util";
 import { gzip } from "node:zlib";
 //#region src/access/policy.ts
@@ -230,6 +230,34 @@ function textButton(options) {
 		}]
 	};
 }
+/**
+* Collapsible fold panel: collapsed by default, grey rounded border, and a
+* built-in right-aligned chevron that flips when expanded. Used for the
+* streaming card's reasoning window and any future "secondary detail" area.
+*/
+function foldPanel(title, content, iconToken) {
+	return {
+		tag: "collapsible_panel",
+		expanded: false,
+		border: {
+			color: "grey",
+			corner_radius: "8px"
+		},
+		header: {
+			title: {
+				tag: "plain_text",
+				content: title
+			},
+			icon: {
+				tag: "standard_icon",
+				token: iconToken
+			},
+			icon_position: "right",
+			icon_expanded_angle: 180
+		},
+		elements: [markdown(content)]
+	};
+}
 /** A row of equal-width columns, each holding one element. */
 function columnSet(columns, options = {}) {
 	return {
@@ -1540,6 +1568,46 @@ var QuestionAnswerer = class {
 };
 //#endregion
 //#region src/cards/streaming.ts
+/**
+* Streaming reply card: the reasoning fold panel, the transient activity
+* lines, the reply body and the settled footer — plus the byte/table budgets
+* that keep one card inside Feishu's limits.
+*
+* Composition, main card:
+*
+*   [fold panel] [activity status] [activity tool] [body]
+*   [hr] [model · session · reasoning time]
+*   [context share · input · output · cache hit]
+*
+* - The panel shows the reasoning behind its own window. While the turn is
+*   still thinking it doubles as the phase indicator; once the turn settles
+*   without any reasoning content (non-reasoning models) it is omitted
+*   entirely instead of leaving an empty bordered box.
+* - The two activity lines are transient: the streamer only passes them for
+*   the card that is currently streaming, so frozen segment cards never repeat
+*   a stale "正在调用工具" line.
+* - The settled footer is a divider plus two notation lines and renders
+*   exactly once: on the main card, only after the turn settles. It carries
+*   the model/effort, session id and the turn's accumulated reasoning time
+*   (line 1), then the context pressure with its window share plus the
+*   input/output token counts and cache hit ratio (line 2). First frames
+*   therefore never show a row of zeroed counters.
+*
+* Continuation cards (`options.segment`) carry a segment header and the body;
+* they have no panel and no footer, so a long answer is not repeated chrome.
+*
+* Budgets, two independent ones:
+* - Each card is measured as a whole: segmentation targets `CARD_TARGET_BYTES`
+*   (main cards probe the panel at its maximum window, so reasoning that keeps
+*   growing after the split cannot push the card over), while `CARD_MAX_BYTES`
+*   is the platform hard cap used only by `buildCard` as an absolute guard.
+* - The reasoning panel is a fixed `REASONING_MAX_BYTES` window, clipped from
+*   the tail with a truncation marker. It neither competes with nor is squeezed
+*   by the reply body: the visible reasoning window is identical whether the
+*   answer is one line or a full segment.
+*
+* @module dsh-channels/cards/streaming
+*/
 const PANEL_TITLES = {
 	thinking: "推理中",
 	replying: "回复中",
@@ -1550,28 +1618,18 @@ const PANEL_TITLES = {
 const PANEL_CHEVRON_TOKEN = "down-small-ccm_outlined";
 /** Feishu hard cap for one card message body. */
 const CARD_MAX_BYTES = 3e4;
-/** Target budget per card — 2 KB below the hard cap as headroom. */
+/** Target budget per card — 2 KB below the hard cap as headroom for the
+*  figures that keep growing between a segment split and the final patch. */
 const CARD_TARGET_BYTES = 28e3;
 /**
-* Hard byte cap for the reasoning fold panel's markdown (5 KB, JSON-escaped
-* UTF-8, including the truncation marker). The panel is clipped against this
-* alone — never against the card — so it neither competes with nor is squeezed
-* by the reply body: the visible reasoning window is identical whether the
-* answer is one line or a full 28 KB segment. Measured at the cap: ≈4.96 K
-* ASCII chars, ≈1.65 K CJK chars, ≈2.5 K emoji. The panel element's own
-* wrapper (border, header, chevron) is charged separately — see
-* `CARD_PANEL_RESERVE_BYTES`.
+* Cap for the reasoning fold panel's markdown (5 KB, JSON-escaped UTF-8,
+* including the truncation marker). The panel is clipped against this alone —
+* never against the card — so the visible reasoning window is the same whether
+* the reply is one line or a full segment. Visible window at the cap: ≈4.96 K
+* ASCII chars, ≈1.65 K CJK chars, ≈1.24 K emoji.
 */
 const REASONING_MAX_BYTES = 5e3;
 /**
-* Bytes held back from the card target for the fold panel as a whole, so a
-* segmented card's body plus its panel stay inside `CARD_TARGET_BYTES`.
-* `REASONING_MAX_BYTES` caps the panel's markdown; the element wrapper around
-* it (border, header, chevron icon, `elements` array) measures a further 315 B
-* at the worst phase, and this reserve covers that with headroom.
-*/
-const CARD_PANEL_RESERVE_BYTES = 5500;
-/**
 * Feishu hard-limits the number of markdown tables a single card may contain
 * (API error 11310 "card table number over limit"; verified on device: the
 * platform allows 5). Segmentation therefore keeps at most 5 tables per card.
@@ -1579,9 +1637,14 @@ const CARD_PANEL_RESERVE_BYTES = 5500;
 const MAX_TABLES_PER_CARD = 5;
 /** Appended to clipped reasoning (and, as an absolute last resort, clipped body). */
 const TRUNCATION_SUFFIX = "\n\n…（内容过长，已截断）";
+const encoder = new TextEncoder();
 /** UTF-8 byte size of a card's JSON — the metric behind Feishu's 30 KB cap. */
-function cardJsonBytes(card) {
-	return new TextEncoder().encode(JSON.stringify(card)).length;
+function cardJsonBytes(value) {
+	return encoder.encode(JSON.stringify(value)).length;
+}
+/** JSON-escaped UTF-8 size of a string, as embedded in a card's JSON. */
+function jsonBytes(text) {
+	return encoder.encode(JSON.stringify(text)).length;
 }
 /**
 * Locate markdown table blocks: runs of ≥ 2 consecutive lines that start with
@@ -1620,6 +1683,42 @@ function tableBlocks(body) {
 	});
 	return blocks;
 }
+/** Fenced code block ranges (opening fence line through the closing line). An
+*  unclosed fence extends to the end of the body. */
+function codeFenceBlocks(body) {
+	const blocks = [];
+	let start = -1;
+	let offset = 0;
+	for (const line of body.split("\n")) {
+		if (/^[ \t]*```/.test(line)) if (start < 0) start = offset;
+		else {
+			blocks.push({
+				start,
+				end: offset + line.length
+			});
+			start = -1;
+		}
+		offset += line.length + 1;
+	}
+	if (start >= 0) blocks.push({
+		start,
+		end: body.length
+	});
+	return blocks;
+}
+/**
+* Move a cut position out of any protected block (code fence or table) it
+* lands inside: the block is kept whole on the following card. A block that
+* starts at position 0 cannot be moved back (that would produce an empty
+* head), so that degenerate case is left to the hard-cut escape hatch.
+*/
+function avoidProtected(blocks, at) {
+	for (const block of blocks) {
+		if (block.start >= at) break;
+		if (at < block.end) return block.start > 0 ? block.start : at;
+	}
+	return at;
+}
 /**
 * Replace markdown table blocks with a placeholder. Used for the reasoning
 * panel, whose content is auxiliary (truncation has no impact) and is never
@@ -1642,21 +1741,42 @@ function stripTables(text) {
 function fmt(n) {
 	return n.toLocaleString("en-US");
 }
+/** Context-window share: one decimal below 10%, a whole number from 10% up. */
+function fmtContextPct(tokens, window) {
+	const pct = tokens / window * 100;
+	return `${Number(pct.toFixed(1)) >= 10 ? pct.toFixed(0) : pct.toFixed(1)}%`;
+}
+/** `上下文 3,618/1,000,000 (0.4%)`; without a usable window the share is omitted. */
 function fmtContext(tokens, window) {
 	if (tokens === void 0) return "—";
-	if (window === void 0) return `${fmt(tokens)} tokens`;
-	return `${fmt(tokens)} / ${fmt(window)}`;
+	if (window === void 0 || window <= 0) return `${fmt(tokens)} tokens`;
+	return `${fmt(tokens)}/${fmt(window)} (${fmtContextPct(tokens, window)})`;
 }
 function fmtCacheHit(pct) {
 	return pct === void 0 ? "—" : `${(pct * 100).toFixed(1)}%`;
 }
-/** Info line 2: `icon - 模型 {model}({effort}) · icon - 缓存命中 {cache} · icon - 上下文 {context}` */
+/** `推理 3.2s` / `推理 1分5s`; `—` when the turn had no reasoning phase. */
+function fmtReasoningTime(ms) {
+	if (ms === void 0) return "—";
+	const safe = Math.max(0, ms);
+	if (safe < 6e4) return `${(safe / 1e3).toFixed(1)}s`;
+	const total = Math.round(safe / 1e3);
+	return `${Math.floor(total / 60)}分${total % 60}s`;
+}
+/**
+* Settled footer, line 1: 🧠 model/effort · 🔑 session id · ⏱ reasoning time.
+* Rendered once, after the turn settles, so live cards never flash a row of
+* zeroed counters.
+*/
 function buildModelLine(stats) {
-	return `🧠 模型 ${stats.model ?? "—"}${stats.effort !== void 0 && stats.effort !== "" ? `(${stats.effort})` : ""} · ⚡ 缓存命中 ${fmtCacheHit(stats.cacheHitPct)} · 📊 上下文 ${fmtContext(stats.contextTokens, stats.contextWindow)}`;
+	return `🧠 模型 ${stats.model ?? "—"}${stats.effort !== void 0 && stats.effort !== "" ? `(${stats.effort})` : ""} · 🔑 会话 ${stats.sessionId} · ⏱ 推理 ${fmtReasoningTime(stats.reasoningMs)}`;
 }
-/** Info line 1: `icon - {session id} · icon - input token {input_token} · icon - output token {output_token}` */
-function buildSessionLine(stats) {
-	return `🔑 ${stats.sessionId} · ⬆ input token ${fmt(stats.inputTokens)} · ⬇ output token ${fmt(stats.outputTokens)}`;
+/**
+* Settled footer, line 2: 📊 context pressure (counts + share) · 📩 input
+* tokens · 📨 output tokens · ⚡ cache hit ratio.
+*/
+function buildUsageLine(stats) {
+	return `📊 上下文 ${fmtContext(stats.contextTokens, stats.contextWindow)} · 📩 输入 ${fmt(stats.inputTokens)} · 📨 输出 ${fmt(stats.outputTokens)} · ⚡ 缓存命中 ${fmtCacheHit(stats.cacheHitPct)}`;
 }
 function reasoningPlaceholder(phase) {
 	return phase === "thinking" ? "*等待模型输出…*" : "*（本次无推理内容）*";
@@ -1664,136 +1784,127 @@ function reasoningPlaceholder(phase) {
 function bodyPlaceholder(phase) {
 	return phase === "done" || phase === "error" ? "*（本次无正文输出）*" : "*正在生成…*";
 }
-/** Continuation header: `📄 回复分段 {n} · {phase}` (or 续上一条卡片 without a number). */
-function segmentHeader(options, phase) {
-	const seg = options.segment;
-	return `📄 ${seg === void 0 ? "续上一条卡片" : `回复分段 ${seg}`} · ${PANEL_TITLES[phase]}`;
+/** The panel's markdown: stripped of tables, with a placeholder when empty. */
+function panelContent(phase, reasoning) {
+	const stripped = stripTables(reasoning);
+	return stripped.trim() === "" ? reasoningPlaceholder(phase) : stripped;
+}
+/**
+* Whether the fold panel renders. `thinking` always does (it carries the
+* phase indicator while the card is otherwise empty); every later phase only
+* when there is actual reasoning to fold away — a settled non-reasoning turn
+* gets no empty bordered box.
+*/
+function panelShown(phase, reasoning) {
+	return phase === "thinking" || stripTables(reasoning).trim() !== "";
 }
-/** Raw card assembly — no clipping of any kind (the budget machinery wraps this). */
-function assemble(phase, reasoning, body, stats, options, status, tool) {
+/** Continuation header: `📄 回复分段 {n}`. */
+function segmentHeader(segment) {
+	return `📄 回复分段 ${segment}`;
+}
+/** Interruption notice header for a repaired continuation card. */
+function interruptionHeader(segment) {
+	return `📄 回复分段 ${segment} · 回复中断`;
+}
+function isSettled(phase) {
+	return phase === "done" || phase === "error";
+}
+/**
+* Defensive cap on caller-supplied activity lines. The streamer already clips
+* them to 64 chars; this bound keeps `buildCard`'s "always ≤ CARD_MAX_BYTES"
+* guarantee even for a direct caller that passes an unbounded line.
+*/
+const ACTIVITY_LINE_MAX_CHARS = 512;
+/** One caller-supplied notation line, defensively capped; undefined when empty. */
+function activityNote(text) {
+	if (text === void 0 || text === "") return void 0;
+	return note(text.length <= ACTIVITY_LINE_MAX_CHARS ? text : `${text.slice(0, ACTIVITY_LINE_MAX_CHARS - 1)}…`);
+}
+/** Render one card. `reasoning`/`body` are the already-budgeted texts. */
+function renderCard(state, options, reasoning, body) {
+	const segment = options.segment;
+	const main = segment === void 0;
 	const elements = [];
-	if (options.panel ?? true) {
-		const panelReasoning = stripTables(reasoning);
-		elements.push({
-			tag: "collapsible_panel",
-			expanded: false,
-			border: {
-				color: "grey",
-				corner_radius: "8px"
-			},
-			header: {
-				title: {
-					tag: "plain_text",
-					content: PANEL_TITLES[phase]
-				},
-				icon: {
-					tag: "standard_icon",
-					token: PANEL_CHEVRON_TOKEN
-				},
-				icon_position: "right",
-				icon_expanded_angle: 180
-			},
-			elements: [{
-				tag: "markdown",
-				content: panelReasoning.trim() === "" ? reasoningPlaceholder(phase) : panelReasoning
-			}]
-		});
-	} else elements.push({
-		tag: "markdown",
-		content: segmentHeader(options, phase),
-		text_size: "notation"
-	});
-	if (status !== void 0 && status !== "") elements.push({
-		tag: "markdown",
-		content: status,
-		text_size: "notation"
-	});
-	if (tool !== void 0 && tool !== "") elements.push({
-		tag: "markdown",
-		content: tool,
-		text_size: "notation"
-	});
-	elements.push({ tag: "hr" });
-	elements.push({
-		tag: "markdown",
-		content: body.trim() === "" ? bodyPlaceholder(phase) : body
-	});
-	elements.push({ tag: "hr" });
-	elements.push({
-		tag: "markdown",
-		content: buildSessionLine(stats),
-		text_size: "notation"
-	});
-	elements.push({
-		tag: "markdown",
-		content: buildModelLine(stats),
-		text_size: "notation"
-	});
-	return {
-		schema: "2.0",
-		config: { width_mode: "fill" },
-		body: { elements }
-	};
+	if (main) {
+		if (panelShown(state.phase, reasoning)) elements.push(foldPanel(PANEL_TITLES[state.phase], panelContent(state.phase, reasoning), PANEL_CHEVRON_TOKEN));
+	} else elements.push(note(segmentHeader(segment)));
+	const statusNote = activityNote(state.status);
+	if (statusNote !== void 0) elements.push(statusNote);
+	const toolNote = activityNote(state.tool);
+	if (toolNote !== void 0) elements.push(toolNote);
+	elements.push(markdown(body.trim() === "" ? bodyPlaceholder(state.phase) : body));
+	if (main && isSettled(state.phase)) {
+		elements.push(divider());
+		elements.push(note(buildModelLine(state.stats)));
+		elements.push(note(buildUsageLine(state.stats)));
+	}
+	return card(elements);
 }
 /**
-* Fit `text` into a byte budget measured by `render`: return `text` unchanged
-* when it already fits; otherwise binary-search the longest prefix that still
-* fits once `suffix` is appended. The result is guaranteed to satisfy the
-* same measurement within `budget`.
+* Longest prefix of `text` that fits `budget` under `measure`.
+*
+* Returns `text` unchanged when it already fits; otherwise the longest prefix
+* with `suffix` appended still fits, so a clipped result is guaranteed to stay
+* within the same budget.
 */
-function clipText(text, suffix, render, budget) {
-	if (render(text) <= budget) return text;
+function fitPrefix(text, budget, measure, suffix = "") {
+	if (measure(text) <= budget) return text;
 	let lo = 0;
 	let hi = text.length;
 	while (lo < hi) {
 		const mid = Math.ceil((lo + hi) / 2);
-		if (render(text.slice(0, mid) + suffix) <= budget) lo = mid;
+		if (measure(text.slice(0, mid) + suffix) <= budget) lo = mid;
 		else hi = mid - 1;
 	}
 	return text.slice(0, lo) + suffix;
 }
-/** JSON-escaped UTF-8 size of a string — the metric Feishu's card cap counts. */
-function jsonBytes(text) {
-	return new TextEncoder().encode(JSON.stringify(text)).length;
+/** Reasoning as rendered: clipped against the panel's own fixed window. */
+function budgetReasoning(state) {
+	return fitPrefix(state.reasoning, REASONING_MAX_BYTES, (content) => jsonBytes(panelContent(state.phase, content)), TRUNCATION_SUFFIX);
 }
 /**
-* JSON-escaped UTF-8 size of the fold panel's markdown, as rendered by one
-* assembled card. Reasoning is budgeted against THIS rather than against the
-* whole card: a card-wide budget makes the panel collapse to the bare
-* truncation marker as soon as the reply body grows, so the visible reasoning
-* window would depend on how long the answer is.
-*/
-function panelMarkdownBytes(render) {
-	return (content) => {
-		const elements = render(content).body?.elements;
-		return jsonBytes(elements?.[0]?.elements?.[0]?.content ?? "");
-	};
-}
-/** JSON-escaped UTF-8 size of the truncation marker — reserved so clips can
-*  never push a card past its budget. */
-const SUFFIX_JSON_BYTES = jsonBytes(TRUNCATION_SUFFIX);
-/**
 * Build one card.
 *
-* - Reasoning is clipped so its markdown stays within `REASONING_MAX_BYTES`
-*   (including the truncation marker): a fixed, self-contained budget that
-*   neither grants space to nor borrows space from the body, so the visible
-*   reasoning window is the same whether the reply is one line or a 28 KB
-*   segment.
-* - The body gets whatever is left of `CARD_MAX_BYTES` once the clipped
-*   reasoning is accounted for, which keeps the total under Feishu's hard cap.
-*   The streamer pre-splits with `segmentCardContent` (probed at the
-*   worst-case phase), so a live stream never reaches this clip: it is a pure
-*   guard for direct callers.
+* The reasoning window is clipped against `REASONING_MAX_BYTES` alone, and the
+* body is then clipped against `CARD_MAX_BYTES` measured on the card that is
+* actually rendered — the guard exists only for direct callers and for the
+* turn-failure notice appended to a settled body; the streamer pre-splits with
+* `segmentCardContent`.
 *
-* Guarantee: the returned card is always ≤ `CARD_MAX_BYTES`, and its panel is
-* always ≤ `REASONING_MAX_BYTES`.
+* Guarantee: the returned card is ≤ `CARD_MAX_BYTES`, and its panel markdown
+* is ≤ `REASONING_MAX_BYTES`.
 */
 function buildCard(state, options = {}) {
-	const render = (reasoning, body) => assemble(state.phase, reasoning, body, state.stats, options, state.status, state.tool);
-	const panelBytes = panelMarkdownBytes((content) => render(content, ""));
-	const reasoning = clipText(state.reasoning, TRUNCATION_SUFFIX, panelBytes, REASONING_MAX_BYTES);
-	return render(reasoning, clipText(state.body, TRUNCATION_SUFFIX, (content) => cardJsonBytes(render("", content)), CARD_MAX_BYTES - panelBytes(reasoning) - SUFFIX_JSON_BYTES));
+	const reasoning = options.segment === void 0 ? budgetReasoning(state) : state.reasoning;
+	return renderCard(state, options, reasoning, fitPrefix(state.body, CARD_MAX_BYTES, (content) => cardJsonBytes(renderCard(state, options, reasoning, content)), TRUNCATION_SUFFIX));
+}
+/**
+* Worst-case panel markdown: exactly `REASONING_MAX_BYTES` JSON bytes of
+* ASCII text (the surrounding quotes cost 2 B).
+*/
+const PANEL_PROBE_MARKDOWN = "r".repeat(REASONING_MAX_BYTES - 2);
+/**
+* Split a body so one card fits: `head` re-renders within `CARD_TARGET_BYTES`
+* and `tail` flows into the next segment card ('' when everything fits).
+*
+* The probe renders the worst card this segment can ever become: the main card
+* always budgets the panel's full window (reasoning may keep growing after the
+* split) and its settled footer, while continuation cards have neither. The
+* `error` phase is probed because it has the longest panel title.
+*/
+function segmentCardContent(state, options = {}) {
+	const main = options.segment === void 0;
+	const probe = {
+		...state,
+		phase: "error",
+		reasoning: main ? PANEL_PROBE_MARKDOWN : ""
+	};
+	const limit = fitPrefix(state.body, CARD_TARGET_BYTES, (content) => cardJsonBytes(renderCard(probe, options, probe.reasoning, content))).length;
+	return splitBodyForCard(state.body, limit);
+}
+/** Card-variant options for one segment (`0` is the main card). */
+function segmentCardOptions(index) {
+	return index === 0 ? {} : { segment: index + 1 };
 }
 /** Interruption notice body for cards repaired after a restart mid-turn. */
 const INTERRUPTION_NOTICE = "⚠️ 服务已重启，本次回复中断，请重新发送消息。";
@@ -1808,57 +1919,18 @@ const INTERRUPTION_NOTICE = "⚠️ 服务已重启，本次回复中断，请
 */
 function buildInterruptionCard(options = {}) {
 	const elements = [];
-	if (options.panel === false) elements.push({
-		tag: "markdown",
-		content: `📄 ${options.segment === void 0 ? "续上一条卡片" : `回复分段 ${options.segment}`} · 回复中断`,
-		text_size: "notation"
-	});
-	elements.push({
-		tag: "markdown",
-		content: INTERRUPTION_NOTICE
-	});
-	return {
-		schema: "2.0",
-		config: { width_mode: "fill" },
-		body: { elements }
-	};
-}
-/**
-* Largest body prefix (char count) whose card renders within `CARD_TARGET_BYTES`
-* minus `CARD_PANEL_RESERVE_BYTES`, reserving the panel's whole footprint for
-* the reasoning that travels with the segment. `segmentCardContent` only ever
-* segments bodies, so reasoning is never a segment budget input by construction
-* — but the panel still occupies the card, so its cap is held back. The probe renders
-* at phase `error`, the worst case (its segment header title is the longest),
-* so a frozen segment can never outgrow the budget merely by the phase flipping
-* 回复中 → 回复失败; stats growth between the split and the final patch consumes
-* the 2 KB redundancy (`CARD_MAX_BYTES` − `CARD_TARGET_BYTES`).
-*/
-function largestBodyPrefix(state, options) {
-	const text = state.body;
-	const budget = CARD_TARGET_BYTES - CARD_PANEL_RESERVE_BYTES;
-	const render = (content) => assemble("error", "", content, state.stats, {
-		...options,
-		panel: false
-	}, state.status, state.tool);
-	if (cardJsonBytes(render(text)) <= budget) return text.length;
-	let lo = 0;
-	let hi = text.length;
-	while (lo < hi) {
-		const mid = Math.ceil((lo + hi) / 2);
-		if (cardJsonBytes(render(text.slice(0, mid))) <= budget) lo = mid;
-		else hi = mid - 1;
-	}
-	return lo;
+	if (options.segment !== void 0) elements.push(note(interruptionHeader(options.segment)));
+	elements.push(markdown(INTERRUPTION_NOTICE));
+	return card(elements);
 }
 /**
 * Split a body at a clean breakpoint so `head` fits one card:
 *  1. the head holds at most `maxTables` whole markdown tables — the boundary
 *     is capped at the first excess table (Feishu rejects cards with more);
-*  2. never inside a fenced code block (pull the boundary back before the fence);
-*  3. never inside a table block (a breakpoint that would land inside one is
-*     moved to its start);
-*  4. then the clean-breakpoint tiers: paragraph blank line → `#` heading line
+*  2. never inside a fenced code block or a table block — the boundary is
+*     pulled back to the block's start (a block beginning the body is left to
+*     the hard-cut escape hatch);
+*  3. then the clean-breakpoint tiers: paragraph blank line → `#` heading line
 *     → line break → hard cut as the escape hatch.
 */
 function splitBodyForCard(body, maxChars, maxTables = 5) {
@@ -1867,67 +1939,25 @@ function splitBodyForCard(body, maxChars, maxTables = 5) {
 		head: body,
 		tail: ""
 	};
-	let limit = maxChars;
-	const firstExcess = tables[maxTables];
-	if (firstExcess !== void 0) limit = Math.min(limit, firstExcess.start);
-	const fencePattern = /^[ \t]*```[^\n]*$/gm;
-	let fenceStart = -1;
-	let inside = false;
-	for (const match of body.matchAll(fencePattern)) {
-		const index = match.index ?? 0;
-		if (!inside) {
-			if (index >= limit) break;
-			inside = true;
-			fenceStart = index;
-		} else if (index >= limit) {
-			if (fenceStart > 0) limit = fenceStart;
-			break;
-		} else inside = false;
-	}
-	if (inside && fenceStart > 0 && fenceStart < limit) limit = fenceStart;
-	for (const block of tables) {
-		if (block.start >= limit) break;
-		if (block.end > limit) {
-			if (block.start > 0) limit = block.start;
-			break;
-		}
-	}
-	/** Move a cut position out of any table block (to just before it). */
-	const avoidTables = (at) => {
-		for (const block of tables) {
-			if (block.start >= at) break;
-			if (at <= block.end && block.start > 0) return block.start;
-		}
-		return at;
-	};
+	const blocks = [...codeFenceBlocks(body), ...tables].sort((a, b) => a.start - b.start);
+	const limit = avoidProtected(blocks, Math.min(maxChars, tables[maxTables]?.start ?? body.length));
 	const window = body.slice(0, limit);
+	const minFill = Math.floor(limit * .7);
 	const cut = (at) => ({
 		head: body.slice(0, at).replace(/\s+$/u, ""),
 		tail: body.slice(at).replace(/^\n+/u, "")
 	});
-	const minFill = Math.floor(limit * .7);
 	const paragraph = window.lastIndexOf("\n\n");
-	if (paragraph >= minFill) return cut(avoidTables(paragraph + 2));
+	if (paragraph >= minFill) return cut(avoidProtected(blocks, paragraph + 2));
 	let heading = -1;
 	for (const match of window.matchAll(/^#{1,6} .*$/gm)) {
 		const start = match.index ?? 0;
 		heading = start === 0 ? 0 : start - 1;
 	}
-	if (heading >= minFill) return cut(avoidTables(heading));
+	if (heading >= minFill) return cut(avoidProtected(blocks, heading));
 	const line = window.lastIndexOf("\n");
-	if (line >= minFill) return cut(avoidTables(line + 1));
-	return {
-		head: body.slice(0, avoidTables(limit)),
-		tail: body.slice(avoidTables(limit))
-	};
-}
-/**
-* How the accumulated body should be laid out for one card: everything that
-* fits (clean breakpoint) plus the remainder for the next segment card.
-* `head` re-renders within `CARD_TARGET_BYTES`; the body is never dropped.
-*/
-function segmentCardContent(state, options = {}) {
-	return splitBodyForCard(state.body, largestBodyPrefix(state, options));
+	if (line >= minFill) return cut(avoidProtected(blocks, line + 1));
+	return cut(limit);
 }
 /**
 * The initial (empty) streaming card for one session: thinking phase, empty
@@ -1946,38 +1976,25 @@ function initialStreamingCard(sessionId) {
 		}
 	});
 }
+//#endregion
+//#region src/cards/onboarding.ts
 /**
 * One-time onboarding card: what the bot does, how workspaces are scoped, and
 * the command cheat sheet. Sent on the first private message of a chat.
+*
+* Static content, deliberately kept apart from the streaming reply card.
+*
+* @module dsh-channels/cards/onboarding
 */
+/** First-contact onboarding card (private chats only, once per chat). */
 function buildOnboardingCard() {
-	return {
-		schema: "2.0",
-		config: { width_mode: "fill" },
-		body: { elements: [
-			{
-				tag: "markdown",
-				content: "**👋 欢迎使用飞书 DSH**"
-			},
-			{
-				tag: "markdown",
-				content: "直接发消息即可开始一个会话，我会在话题里流式回复；话题内继续发消息无需再 @ 我。"
-			},
-			{
-				tag: "markdown",
-				content: "**工作区**：私聊一人一个；群里每位成员各自一个，互不影响。"
-			},
-			{
-				tag: "markdown",
-				content: "**常用命令**：`/help` 命令列表 · `/status` 会话状态 · `/workspace` 工作目录\n`/effort` 推理强度 · `/model` 模型 · `/permissions` 权限预设\n`/new` 新建会话 · `/stop` 中断当前回合 · `/history` 历史 · `/export` 导出日志"
-			},
-			{
-				tag: "markdown",
-				content: "需要授权或补充信息时，我会发一张卡片，点按钮或直接回复即可。",
-				text_size: "notation"
-			}
-		] }
-	};
+	return card([
+		markdown("**👋 欢迎使用飞书 DSH**"),
+		markdown("直接发消息即可开始一个会话，我会在话题里流式回复；话题内继续发消息无需再 @ 我。"),
+		markdown("**工作区**：私聊一人一个；群里每位成员各自一个，互不影响。"),
+		markdown("**常用命令**：`/help` 命令列表 · `/status` 会话状态 · `/workspace` 工作目录\n`/effort` 推理强度 · `/model` 模型 · `/permissions` 权限预设\n`/new` 新建会话 · `/stop` 中断当前回合 · `/history` 历史 · `/export` 导出日志"),
+		note("需要授权或补充信息时，我会发一张卡片，点按钮或直接回复即可。")
+	]);
 }
 //#endregion
 //#region src/commands/registry.ts
@@ -2436,8 +2453,16 @@ const routeRecordSchema = z.object({
 	chatType: z.enum(["p2p", "group"]),
 	/** Workspace owner (sender open_id). */
 	senderOpenId: z.string().min(1),
-	/** Workspace directory for this (chat, user) pair. */
+	/** Workspace root owning this route: the Session header cwd / sandbox root. */
 	workspacePath: z.string().min(1),
+	/**
+	* Effective working directory of the bound Session (the per-topic directory
+	* or Git worktree checkout). Absent on records written before per-topic
+	* directories existed: `workspacePath` is then the working directory too.
+	*/
+	sessionDir: z.string().min(1).optional(),
+	/** Git branch owning `sessionDir` when it is a worktree checkout. */
+	worktreeBranch: z.string().min(1).optional(),
 	/** Message id of the latest streaming card (updated per turn). */
 	cardMessageId: z.string().min(1),
 	/** Epoch ms when the record was created. */
@@ -2469,6 +2494,12 @@ const expiredRouteRecordSchema = z.object({
 	/** Workspace the retired route belonged to; absent in tombstones written by
 	*  older plugin versions, so the field must stay optional. */
 	workspacePath: z.string().min(1).optional(),
+	/** Effective working directory the retired route's Session used; absent in
+	*  legacy tombstones (retention cleanup then treats `workspacePath` as the
+	*  directory, matching pre-v2 routes). */
+	sessionDir: z.string().min(1).optional(),
+	/** Git branch of that directory when it was a worktree checkout. */
+	worktreeBranch: z.string().min(1).optional(),
 	/** Epoch ms of the last activity through the route before retirement.
 	*  Optional for the same legacy-compatibility reason; consumers fall back to
 	*  `expiredAt` when it is absent. */
@@ -2509,6 +2540,14 @@ function appendSessionHistory(record, sessionId, createdAt) {
 		}]
 	});
 }
+/**
+* Effective working directory of one route's Session. Records written before
+* per-topic directories have no `sessionDir`; their workspace path is the
+* directory the Session really works in.
+*/
+function sessionDirOf(record) {
+	return record.sessionDir ?? record.workspacePath;
+}
 const inflightCardSchema = z.object({
 	/** Feishu message id of one segment card. */
 	messageId: z.string().min(1),
@@ -2653,34 +2692,211 @@ function chatRouteKey(chatType, chatId, senderOpenId) {
 	return chatType === "p2p" ? `chat:p2p:${chatId}:${senderOpenId}` : `chat:group:${chatId}:${senderOpenId}`;
 }
 //#endregion
+//#region src/workspaces.ts
+/**
+* Workspace directory resolution: one DSH workspace per user, one working
+* directory per Feishu topic.
+*
+* - p2p:   workspace `<baseDir>/p2p/<open_id>/`
+* - group: workspace `<baseDir>/groups/<chat_id>/<open_id>/`
+* - topic: `<workspace>/topics/<topic-token>/` (the Session's effective cwd)
+*
+* The workspace root is the Session header cwd: it keeps the Session grouped
+* under the user's project in the GUI and stays the sandbox write boundary.
+* The per-topic directory is where the tools actually work (see
+* `./session/isolation.ts`), so files produced by different topics never mix.
+* Older versions registered one workspace per topic under `<baseDir>/topics/`;
+* those directories are kept verbatim for legacy routes and are only removed
+* by the retention cleanup, never migrated.
+*
+* Attachments received before a topic exists are staged below
+* `<baseDir>/_staging/<chatType>/<chat_id>/<open_id>/` and adopted into the
+* topic directory once its first Session is created.
+*
+* Feishu ids (`ou_…`, `oc_…`) are safe path segments, but they are validated
+* anyway so a hostile id can never escape `baseDir`.
+*
+* @module dsh-channels/workspaces
+*/
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+/** Upper bound for a panel-supplied workspace root (filesystem path limit headroom). */
+const MAX_BASE_DIR_LENGTH = 4096;
+/**
+* Validate and normalize a workspace root supplied by the settings panel.
+*
+* The profile layer keeps accepting whatever the deployment wrote (including
+* the historical relative default), but a value *typed into the Web panel*
+* must name an unambiguous location: a relative path would resolve against
+* the host process's unpredictable cwd. `~` is expanded for convenience and
+* the result is normalized; the root itself is rejected because workspace
+* directories are appended to it.
+*
+* @param raw - untrusted panel value.
+* @param home - home directory seam (tests pin it; production uses `homedir()`).
+* @returns the normalized absolute path, or a user-facing message.
+*/
+function normalizeWorkspaceBaseDir(raw, home = homedir()) {
+	if (typeof raw !== "string") return {
+		ok: false,
+		message: "必须是字符串"
+	};
+	const trimmed = raw.trim();
+	if (trimmed === "") return {
+		ok: false,
+		message: "不能为空"
+	};
+	if (trimmed.length > MAX_BASE_DIR_LENGTH) return {
+		ok: false,
+		message: `路径长度不得超过 ${MAX_BASE_DIR_LENGTH} 个字符`
+	};
+	if (/[\u0000-\u001f\u007f]/.test(trimmed)) return {
+		ok: false,
+		message: "包含非法控制字符"
+	};
+	let expanded = trimmed;
+	if (expanded === "~") expanded = home;
+	else if (expanded.startsWith("~/") || expanded.startsWith("~\\")) expanded = path.join(home, expanded.slice(2));
+	if (!path.isAbsolute(expanded)) return {
+		ok: false,
+		message: "必须是绝对路径（例如 /Users/you/.dsh/dsh-channels/workspaces）"
+	};
+	const normalized = path.resolve(expanded);
+	if (path.parse(normalized).root === normalized) return {
+		ok: false,
+		message: "不能使用文件系统根目录"
+	};
+	return {
+		ok: true,
+		value: normalized
+	};
+}
+/**
+* Materialize one panel-supplied workspace root and prove it is usable.
+*
+* Called when the panel saves `baseDir` so an unusable location fails at save
+* time instead of surfacing later as "会话创建失败" inside a Feishu chat.
+* The directory is created here (the same `mkdir -p` the first session would
+* perform); an existing non-directory is refused.
+*
+* @returns an error message, or `undefined` when the directory is writable.
+*/
+async function prepareWorkspaceBaseDir(dir) {
+	try {
+		await mkdir(dir, { recursive: true });
+	} catch (error) {
+		return `无法创建工作区目录：${String(error)}`;
+	}
+	try {
+		if (!(await stat(dir)).isDirectory()) return "该路径已存在但不是目录";
+	} catch (error) {
+		return `无法读取工作区目录：${String(error)}`;
+	}
+	try {
+		await access(dir, constants.W_OK);
+	} catch {
+		return "工作区目录不可写";
+	}
+}
+function safeSegment(raw, what) {
+	const segment = raw.replace(/^\/+|\/+$/g, "");
+	if (!SAFE_SEGMENT.test(segment) || segment === "." || segment === "..") throw new Error(`dsh-channels: unsafe ${what} for workspace path: ${JSON.stringify(raw)}`);
+	return segment;
+}
+/**
+* Stable, filesystem-safe token for one Feishu conversation: a real topic uses
+* its thread id, while a degraded chat-scoped conversation uses the Session id
+* that owns it (there is no topic boundary to key on).
+*/
+function topicTokenFor(routeKey, kind, sessionId) {
+	return kind === "thread" ? safeSegment(routeKey, "route key") : safeSegment(sessionId, "session id");
+}
+/** Git branch (and worktree directory) name for one topic token. */
+function worktreeBranchFor(topicToken) {
+	return `feishu-${safeSegment(topicToken, "topic token")}`;
+}
+/**
+* Deterministic workspace directory for one user in one chat context: the
+* durable project the user's Sessions are grouped under.
+*
+* - p2p:   `<baseDir>/p2p/<open_id>/`
+* - group: `<baseDir>/groups/<chat_id>/<open_id>/`
+*
+* These are the same paths older versions used as their shared (user × chat)
+* workspaces, so an upgraded deployment reuses the existing registry record
+* instead of creating a second project for the same user.
+*/
+function workspacePathFor(baseDir, chatType, chatId, senderOpenId) {
+	const user = safeSegment(senderOpenId, "senderOpenId");
+	if (chatType === "p2p") return path.join(baseDir, "p2p", user);
+	return path.join(baseDir, "groups", safeSegment(chatId, "chatId"), user);
+}
+/** Per-topic working directory inside one user workspace. */
+function topicDirFor(workspacePath, topicToken) {
+	return path.join(workspacePath, "topics", safeSegment(topicToken, "topic token"));
+}
+/**
+* Root of the legacy (one workspace per topic) directories. Legacy workspaces
+* live strictly below this path, which is how the retention cleanup tells them
+* apart from user workspaces that must never be deleted.
+*/
+function legacyTopicWorkspaceRoot(baseDir) {
+	return path.join(baseDir, "topics");
+}
+/**
+* Staging directory for attachments that arrive before their topic (and so
+* its topic directory) exists. Not a registered workspace: files move into the
+* real topic directory as soon as the first Session of that topic is created.
+*/
+function stagingPathFor(baseDir, chatType, chatId, senderOpenId) {
+	const chat = safeSegment(chatId, "chatId");
+	const user = safeSegment(senderOpenId, "senderOpenId");
+	return path.join(baseDir, "_staging", chatType, chat, user);
+}
+/** Human-friendly workspace title shown in the DSH workspace list. */
+function workspaceTitleFor(chatType, chatId, senderOpenId) {
+	return chatType === "p2p" ? `飞书私聊 · ${senderOpenId}` : `飞书群聊 · ${chatId} · ${senderOpenId}`;
+}
+/**
+* Ensure one user's workspace directory exists and is registered with the
+* host's workspace registry. Idempotent: repeated calls return the same record,
+* and an existing record keeps its (possibly renamed) title.
+*/
+async function ensureWorkspace(ctx, baseDir, chatType, chatId, senderOpenId) {
+	const dir = workspacePathFor(baseDir, chatType, chatId, senderOpenId);
+	await mkdir(dir, { recursive: true });
+	return ctx.workspaceRegistry.create(dir, workspaceTitleFor(chatType, chatId, senderOpenId));
+}
+//#endregion
 //#region src/cleanup.ts
 /**
-* Stale workspace cleanup: pure planning and application policy.
+* Retention cleanup policy: pure planning and application over injected seams.
 *
-* The plugin creates one host workspace per (user × chat) pair below its
-* configured `baseDir` (see `workspaces.ts`). The host never removes those
-* directories on its own, so a long-running deployment slowly accumulates
-* attachments and agent output for conversations nobody uses anymore. This
-* module decides which plugin-created workspaces are stale and applies the
-* removal while deliberately owning no I/O: every filesystem and registry
-* effect is injected through `CleanupDeps`, which keeps the policy small and
-* testable and keeps the dangerous half (recursive deletion + registry
-* unregistration) in the caller.
+* Conversations produce files below two kinds of directories the host never
+* removes on its own:
 *
-* Activity precedence for one workspace:
+* 1. **Per-topic session directories** (current layout): the effective working
+*    directory of one Feishu topic — `<user-workspace>/topics/<token>` or a Git
+*    worktree checkout. They are not registered workspaces, so their activity
+*    comes from route records/tombstones or from the directory's own `mtime`.
+* 2. **Legacy one-workspace-per-topic directories** written by older plugin
+*    versions (`<baseDir>/topics/...`). Those are still registered host
+*    workspaces and are unregistered when removed.
 *
-* 1. the newest `lastActivityAt` among its active routes; a workspace with a
-*    live session is never offered for deletion,
-* 2. otherwise the newest tombstone that names the workspace
-*    (`lastActivityAt`, falling back to `expiredAt` for tombstones written
-*    before routes recorded their workspace path),
-* 3. otherwise the directory's own `mtime` (an orphan workspace).
+* User workspaces themselves (the durable project each user/chat is grouped
+* under) are never candidates. This module owns no I/O: every filesystem and
+* registry effect is injected through `CleanupDeps`, so the policy stays small
+* and testable while the dangerous half (recursive deletion + registry
+* unregistration) stays in the caller.
 *
-* Tombstones written before this feature carry neither `workspacePath` nor
-* `lastActivityAt`, so they cannot be attributed to a workspace; such a
-* workspace falls through to the `mtime` rule instead. A workspace with no
-* usable activity evidence at all (missing or unreadable directory) is never
-* offered for deletion: irreversible removal requires positive evidence.
+* Activity precedence:
+*
+* 1. the newest `lastActivityAt` among the active routes bound to the target;
+*    a target with a live Session is never offered for deletion,
+* 2. otherwise the newest tombstone that names it,
+* 3. otherwise the directory's own `mtime` (an orphan directory).
+*
+* A directory with no usable activity evidence at all (missing/unreadable) is
+* never offered for deletion: irreversible removal requires positive evidence.
 *
 * @module dsh-channels/cleanup
 */
@@ -2712,14 +2928,21 @@ function retentionMs(value) {
 /** Title prefixes `workspaces.ts` gives plugin-created workspaces. */
 const PLUGIN_TITLE_PREFIXES = ["飞书私聊 ·", "飞书群聊 ·"];
 /**
+* Whether a title was produced by this plugin (as opposed to a project the
+* operator registered by hand). Cleanup only ever touches plugin workspaces.
+*/
+function pluginWorkspaceTitle(title) {
+	return PLUGIN_TITLE_PREFIXES.some((prefix) => title.startsWith(prefix));
+}
+/**
 * Whether `target` is strictly below `baseDir`.
 *
 * Both sides are normalized lexically (`path.resolve`), so a `..` segment or a
 * relative value cannot escape `baseDir`; the base directory itself and
 * siblings sharing a name prefix (e.g. `base-other`) are not "inside". The
 * check is lexical on purpose: this module owns no I/O. The caller's
-* `removeWorkspace` should still refuse symlinked escapes with a realpath
-* check before deleting.
+* `removeWorkspace` / `removeSessionDir` must still refuse symlinked escapes
+* with a realpath check before deleting.
 *
 * @param baseDir - directory the target must stay below.
 * @param target - candidate path.
@@ -2733,60 +2956,51 @@ function isPathInside(baseDir, target) {
 	if (relative === "" || path.isAbsolute(relative)) return false;
 	return relative !== ".." && !relative.startsWith(`..${path.sep}`);
 }
-/** Whether a host workspace title marks the workspace as plugin-created. */
-function pluginWorkspaceTitle(title) {
-	return PLUGIN_TITLE_PREFIXES.some((prefix) => title.startsWith(prefix));
-}
-/** Lexical path equality (both sides resolved the same way as `isPathInside`). */
+/** Lexically compare two paths (both resolved) without touching the disk. */
 function samePath(left, right) {
 	return path.resolve(left) === path.resolve(right);
 }
-/** Newest finite timestamp of a list, or `undefined` when none is usable. */
+/** Whether a path is a filesystem root (never deletable). */
+function isFilesystemRoot(target) {
+	const resolved = path.resolve(target);
+	return path.parse(resolved).root === resolved;
+}
+/** Newest value of a list, or `undefined` when empty. */
 function newestActivity(values) {
-	let newest;
-	for (const value of values) {
-		if (!Number.isFinite(value)) continue;
-		if (newest === void 0 || value > newest) newest = value;
-	}
-	return newest;
+	return values.length === 0 ? void 0 : Math.max(...values);
 }
-/** Count/byte values never go negative or non-finite on the outcome path. */
 function nonNegative(value) {
 	return Number.isFinite(value) && value > 0 ? value : 0;
 }
-/** Best-effort error text (never a stack trace). */
-function errorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
-}
-/** A filesystem root must never become the cleanup base directory. */
-function isFilesystemRoot(dir) {
-	return path.parse(dir).root === dir;
+async function readWorkspaceStats(deps, directory) {
+	try {
+		return await deps.statWorkspace(directory);
+	} catch (error) {
+		deps.warn?.(`dsh-channels: cleanup stats unavailable for ${directory}: ${String(error)}`);
+		return;
+	}
 }
-/** Liveness probe that fails safe: an unknowable session counts as live. */
 function sessionIsLive(deps, sessionId) {
 	try {
 		return deps.isLive(sessionId);
 	} catch (error) {
-		deps.warn?.(`dsh-channels: workspace cleanup liveness check failed for ${sessionId}: ${errorMessage(error)}`);
+		deps.warn?.(`dsh-channels: cleanup liveness probe failed for ${sessionId}: ${String(error)}`);
 		return true;
 	}
 }
-/** Measure one directory, tolerating a throwing or absent implementation. */
-async function readWorkspaceStats(deps, workspacePath) {
-	try {
-		return await deps.statWorkspace(workspacePath);
-	} catch (error) {
-		deps.warn?.(`dsh-channels: workspace stats unavailable for ${workspacePath}: ${errorMessage(error)}`);
-		return;
-	}
+function routesAreLive(deps, routes) {
+	return routes.some((route) => sessionIsLive(deps, route.sessionId));
+}
+/** Effective directory of one route (workspace path on legacy routes). */
+function directoryOfRoute(route) {
+	return route.sessionDir ?? route.workspacePath;
 }
 /**
-* Build the dry-run cleanup plan for the configured retention window.
+* Decide which directories are stale, without deleting anything.
 *
-* Only plugin-created workspaces (`飞书私聊 ·` / `飞书群聊 ·` titles) strictly
-* below `baseDir` are considered. A workspace is a candidate when its newest
-* activity is older than the cutoff; its footprint is measured for the panel
-* preview and for `freedBytes` reporting.
+* Only plugin-created targets strictly below `baseDir` are considered. User
+* workspaces are never candidates; legacy one-workspace-per-topic directories
+* are candidates only below `<baseDir>/topics/`.
 *
 * @param deps - injected effect seams (nothing is deleted here).
 * @returns the plan, or `undefined` when retention is off or the base
@@ -2797,40 +3011,116 @@ async function planWorkspaceCleanup(deps) {
 	if (window === void 0) return void 0;
 	const baseDir = path.resolve(deps.baseDir);
 	if (isFilesystemRoot(baseDir)) {
-		deps.warn?.("dsh-channels: workspace cleanup disabled: baseDir is a filesystem root");
+		deps.warn?.("dsh-channels: retention cleanup disabled: baseDir is a filesystem root");
 		return;
 	}
+	const legacyRoot = legacyTopicWorkspaceRoot(baseDir);
 	const cutoff = (deps.now?.() ?? Date.now()) - window;
 	const activeRoutes = await deps.activeRoutes();
 	const tombstones = await deps.tombstones();
+	const workspaces = await deps.listWorkspaces();
 	const candidates = [];
 	let skippedLive = 0;
-	for (const workspace of await deps.listWorkspaces()) {
+	const userWorkspacePaths = /* @__PURE__ */ new Set();
+	for (const workspace of workspaces) {
+		const resolved = path.resolve(workspace.path);
+		if (!pluginWorkspaceTitle(workspace.title)) continue;
+		if (!isPathInside(baseDir, resolved)) continue;
+		if (isPathInside(legacyRoot, resolved)) continue;
+		userWorkspacePaths.add(resolved);
+	}
+	for (const workspace of workspaces) {
 		if (!pluginWorkspaceTitle(workspace.title)) continue;
-		if (!isPathInside(baseDir, workspace.path)) continue;
-		const routes = activeRoutes.filter((route) => samePath(route.workspacePath, workspace.path));
-		if (routes.some((route) => sessionIsLive(deps, route.sessionId))) {
+		const targetPath = path.resolve(workspace.path);
+		if (!isPathInside(baseDir, targetPath)) continue;
+		if (!isPathInside(legacyRoot, targetPath)) continue;
+		const routes = activeRoutes.filter((route) => samePath(route.workspacePath, targetPath) && (route.sessionDir === void 0 || samePath(route.sessionDir, targetPath)));
+		if (routesAreLive(deps, routes)) {
 			skippedLive++;
 			continue;
 		}
 		let stats;
 		let activityAt = newestActivity(routes.map((route) => route.lastActivityAt));
-		if (activityAt === void 0) activityAt = newestActivity(tombstones.filter((tombstone) => tombstone.workspacePath !== void 0 && samePath(tombstone.workspacePath, workspace.path)).map((tombstone) => tombstone.lastActivityAt ?? tombstone.expiredAt));
+		if (activityAt === void 0) activityAt = newestActivity(tombstones.filter((tombstone) => tombstone.workspacePath !== void 0 && samePath(tombstone.workspacePath, targetPath) && (tombstone.sessionDir === void 0 || samePath(tombstone.sessionDir, targetPath))).map((tombstone) => tombstone.lastActivityAt ?? tombstone.expiredAt));
 		if (activityAt === void 0) {
-			stats = await readWorkspaceStats(deps, workspace.path);
+			stats = await readWorkspaceStats(deps, targetPath);
 			activityAt = stats !== void 0 && Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : void 0;
 		}
 		if (activityAt === void 0 || activityAt >= cutoff) continue;
-		stats ??= await readWorkspaceStats(deps, workspace.path);
+		stats ??= await readWorkspaceStats(deps, targetPath);
 		candidates.push({
-			workspace,
+			target: {
+				kind: "workspace",
+				workspace
+			},
+			path: workspace.path,
 			activityAt,
 			bytes: stats === void 0 ? 0 : nonNegative(stats.bytes),
 			files: stats === void 0 ? 0 : nonNegative(stats.files),
 			routes
 		});
 	}
-	candidates.sort((left, right) => left.activityAt - right.activityAt || left.workspace.path.localeCompare(right.workspace.path));
+	const dirs = /* @__PURE__ */ new Map();
+	const evidenceFor = (directory) => {
+		const key = path.resolve(directory);
+		let evidence = dirs.get(key);
+		if (evidence === void 0) {
+			evidence = {
+				routes: [],
+				tombstoneActivity: []
+			};
+			dirs.set(key, evidence);
+		}
+		return evidence;
+	};
+	/** Whether a directory is a plausible per-topic dir (never a workspace root). */
+	const acceptable = (directory) => {
+		const resolved = path.resolve(directory);
+		if (isFilesystemRoot(resolved)) return false;
+		if (!isPathInside(baseDir, resolved)) return false;
+		if (resolved === legacyRoot || isPathInside(legacyRoot, resolved)) return false;
+		if (userWorkspacePaths.has(resolved)) return false;
+		return true;
+	};
+	for (const route of activeRoutes) {
+		if (route.sessionDir === void 0 || samePath(route.sessionDir, route.workspacePath)) continue;
+		if (!acceptable(route.sessionDir)) continue;
+		evidenceFor(route.sessionDir).routes.push(route);
+	}
+	for (const tombstone of tombstones) {
+		if (tombstone.sessionDir === void 0) continue;
+		if (tombstone.workspacePath !== void 0 && samePath(tombstone.sessionDir, tombstone.workspacePath)) continue;
+		if (!acceptable(tombstone.sessionDir)) continue;
+		evidenceFor(tombstone.sessionDir).tombstoneActivity.push(tombstone.lastActivityAt ?? tombstone.expiredAt);
+	}
+	for (const scanned of await deps.listSessionDirs()) {
+		if (!acceptable(scanned.path)) continue;
+		evidenceFor(scanned.path).mtimeMs = scanned.mtimeMs;
+	}
+	for (const [directory, evidence] of dirs) {
+		if (routesAreLive(deps, evidence.routes)) {
+			skippedLive++;
+			continue;
+		}
+		let activityAt = newestActivity(evidence.routes.map((route) => route.lastActivityAt));
+		activityAt ??= newestActivity(evidence.tombstoneActivity);
+		activityAt ??= evidence.mtimeMs;
+		if (activityAt === void 0 || activityAt >= cutoff) continue;
+		const stats = await readWorkspaceStats(deps, directory);
+		if (stats === void 0 && evidence.routes.length === 0) continue;
+		candidates.push({
+			target: {
+				kind: "session-dir",
+				path: directory
+			},
+			path: directory,
+			activityAt,
+			bytes: stats === void 0 ? 0 : nonNegative(stats.bytes),
+			files: stats === void 0 ? 0 : nonNegative(stats.files),
+			routes: evidence.routes
+		});
+	}
+	candidates.sort((left, right) => left.activityAt - right.activityAt || left.path.localeCompare(right.path));
 	return {
 		retentionMs: window,
 		cutoff,
@@ -2839,56 +3129,68 @@ async function planWorkspaceCleanup(deps) {
 	};
 }
 /**
-* Apply a plan: retire the candidate's active routes, then remove the
-* workspace directory and its registry record.
+* Apply a plan: retire the candidate's active routes, then remove its
+* directory (and, for legacy workspaces, the registry record).
 *
 * A candidate is the unit of failure: if retiring any of its routes fails, the
-* workspace is left untouched (route bookkeeping must not point at a deleted
+* directory is left untouched (route bookkeeping must not point at a deleted
 * directory), the failure is collected, and the remaining candidates are still
 * processed. Paths are revalidated immediately before the destructive step, so
-* a stale or hand-built plan can never delete something outside `baseDir` (or
-* `baseDir` itself).
+* a stale or hand-built plan can never delete `baseDir` itself, a user
+* workspace, or something outside `baseDir`.
 *
 * @param deps - injected effect seams.
 * @param plan - plan produced by `planWorkspaceCleanup` (or an equivalent preview).
-* @returns aggregate counts plus per-workspace failures.
+* @returns aggregate counts plus per-target failures.
 */
 async function applyWorkspaceCleanup(deps, plan) {
 	const baseDir = path.resolve(deps.baseDir);
 	const baseDirIsRoot = isFilesystemRoot(baseDir);
+	const legacyRoot = legacyTopicWorkspaceRoot(baseDir);
+	const registered = new Set((await deps.listWorkspaces()).filter((workspace) => pluginWorkspaceTitle(workspace.title)).map((workspace) => path.resolve(workspace.path)));
 	const failures = [];
 	let deletedWorkspaces = 0;
+	let deletedSessionDirs = 0;
 	let retiredRoutes = 0;
 	let freedBytes = 0;
 	for (const candidate of plan.candidates) {
-		const target = candidate.workspace.path;
-		if (baseDirIsRoot || !isPathInside(baseDir, target)) {
+		const target = candidate.target;
+		const targetPath = candidate.path;
+		const insideBase = !baseDirIsRoot && isPathInside(baseDir, targetPath);
+		const inLegacyRoot = isPathInside(legacyRoot, targetPath);
+		if (!(target.kind === "workspace" ? insideBase && inLegacyRoot : insideBase && !inLegacyRoot && !registered.has(path.resolve(targetPath)))) {
 			failures.push({
-				path: target,
-				message: "refused: workspace path is outside the cleanup base directory"
+				path: targetPath,
+				message: "refused: path is not a cleanable plugin directory"
 			});
 			continue;
 		}
 		try {
 			for (const route of candidate.routes) {
-				if (!samePath(route.workspacePath, target)) continue;
+				if (!samePath(directoryOfRoute(route), targetPath)) continue;
 				await deps.retireRoute(route);
 				retiredRoutes++;
 			}
-			await deps.removeWorkspace(candidate.workspace);
-			deletedWorkspaces++;
+			if (target.kind === "workspace") {
+				await deps.removeWorkspace(target.workspace);
+				deletedWorkspaces++;
+			} else {
+				await deps.removeSessionDir(targetPath);
+				deletedSessionDirs++;
+			}
 			freedBytes += nonNegative(candidate.bytes);
 		} catch (error) {
-			const message = errorMessage(error);
+			const message = error instanceof Error ? error.message : String(error);
 			failures.push({
-				path: target,
+				path: targetPath,
 				message
 			});
-			deps.warn?.(`dsh-channels: workspace cleanup failed for ${target}: ${message}`);
+			deps.warn?.(`dsh-channels: cleanup failed for ${targetPath}: ${message}`);
 		}
 	}
 	return {
 		deletedWorkspaces,
+		deletedSessionDirs,
 		retiredRoutes,
 		freedBytes,
 		failures
@@ -3009,6 +3311,8 @@ var RouteStore = class {
 			senderOpenId: record.senderOpenId,
 			expiredAt: now,
 			workspacePath: record.workspacePath,
+			...record.sessionDir === void 0 ? {} : { sessionDir: record.sessionDir },
+			...record.worktreeBranch === void 0 ? {} : { worktreeBranch: record.worktreeBranch },
 			lastActivityAt: record.lastActivityAt
 		};
 		await this.deps.domain()?.expiredRoutes.put(key, tombstone);
@@ -3135,11 +3439,7 @@ var InflightRepair = class {
 		if (channel === void 0) throw new Error("dsh-channels: channel not started");
 		for (const [index, card] of snapshot.cards.entries()) {
 			if (card.mode !== "card") continue;
-			const options = index === 0 ? {} : {
-				panel: false,
-				segment: index + 1
-			};
-			await channel.updateCard(card.messageId, buildInterruptionCard(options));
+			await channel.updateCard(card.messageId, buildInterruptionCard(segmentCardOptions(index)));
 		}
 		if (snapshot.reactionId !== void 0) await channel.removeReaction(snapshot.triggerMessageId, snapshot.reactionId).catch(() => {});
 		await channel.addReaction(snapshot.triggerMessageId, "DONE").catch(() => {});
@@ -3157,13 +3457,13 @@ const FEISHU_ATTACHMENTS_SECTION = "dsh-channels:feishu-attachments";
 const FEISHU_ATTACHMENTS_ORDER = 950;
 /** Model-facing text. Kept stable so unchanged sessions keep their KV cache. */
 const FEISHU_ATTACHMENTS_GUIDANCE = `## Feishu attachments
-Every Feishu conversation (topic) has its own workspace and its own attachments directory. Images, files, and forwarded chat records sent through Feishu are archived verbatim in this conversation's \`attachments/\` directory. Each file name starts with its receipt time (\`YYYYMMDD-HHmmss-\`), so newer attachments sort later and \`ls -lt <dir>\` lists the newest first.
+Every Feishu conversation (topic) has its own working directory inside its user's workspace, and every working directory has its own \`attachments/\` directory. Images, files, and forwarded chat records sent through Feishu are archived verbatim in this conversation's \`attachments/\` directory. Each file name starts with its receipt time (\`YYYYMMDD-HHmmss-\`), so newer attachments sort later and \`ls -lt <dir>\` lists the newest first.
 
 Attachments are never inserted into the conversation automatically. Read them only when the user's request needs them, and do not read attachments the user did not mention:
 - images: use \`read_image\` with the file path;
 - text and code: use \`read\` when the session mounts that tool, otherwise \`bash\` (for example \`sed -n '1,200p' <file>\`);
 - other formats (PDF, Office, archives, ...): inspect or convert them with \`bash\`.
-If the user refers to "the file/image I just sent" without a name, list this conversation's attachments directory and pick the most recent matching attachment. Other Feishu conversations have separate workspaces: never read outside this workspace, and never mention files from another conversation.`;
+If the user refers to "the file/image I just sent" without a name, list this conversation's attachments directory and pick the most recent matching attachment. Other Feishu conversations work in separate directories: never read outside this conversation's working directory, and never mention files from another conversation.`;
 /**
 * Full guidance for one Session. The absolute per-session directory is
 * appended when known so the convention still resolves after the Agent changes
@@ -3808,155 +4108,159 @@ function installRequestPolicy(agentCtx, config = {}) {
 	};
 }
 //#endregion
-//#region src/workspaces.ts
+//#region src/session/isolation.ts
 /**
-* Workspace directory resolution: one DSH workspace per (user × chat).
+* Per-topic Session placement: which directory each Feishu conversation works
+* in, without growing the host workspace list with every topic.
 *
-* Every Feishu topic gets its own workspace, grouped by the (chat, user) pair:
-* - p2p:    `<baseDir>/p2p/<open_id>/<topic>/`
-* - group:  `<baseDir>/groups/<chat_id>/<open_id>/<topic>/`
+* A Session's **header cwd** is fixed at creation and decides two things:
+* its workspace-registry membership (the GUI project it is grouped under) and
+* the sandbox write boundary. The **effective working directory** is a mutable
+* Session projection (`ctx.workingDirectory`), persisted in the Session log
+* and restored on resume; the bash/fs/terminal tools resolve it before every
+* call.
 *
-* Attachments received before a topic exists are staged below
-* `<baseDir>/_staging/<chatType>/<chat_id>/<open_id>/` and adopted into the
-* topic workspace once its first Session is created.
+* This module plans one topic's placement:
 *
-* Feishu ids (`ou_…`, `oc_…`) are safe path segments, but they are validated
-* anyway so a hostile id can never escape `baseDir`.
+* - `subdir`: `<workspace>/topics/<token>` — a plain directory switched to via
+*   `workingDirectory.set`.
+* - `worktree`: a Git worktree created through `ctx.worktrees` (branch
+*   `feishu-<token>`), used when the workspace is a Git repository or when the
+*   deployment forces it.
 *
-* @module dsh-channels/workspaces
-*/
-const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
-/** Upper bound for a panel-supplied workspace root (filesystem path limit headroom). */
-const MAX_BASE_DIR_LENGTH = 4096;
-/**
-* Validate and normalize a workspace root supplied by the settings panel.
+* Both modes keep the Session's header cwd on the workspace root, so the
+* Session stays grouped under the user's project. When the host exposes no
+* `workingDirectory` service (unusual: it ships with `dsh-base`), the Session
+* is created directly in the topic directory instead — file isolation still
+* holds, but the Session can no longer be attached to the workspace.
 *
-* The profile layer keeps accepting whatever the deployment wrote (including
-* the historical relative default), but a value *typed into the Web panel*
-* must name an unambiguous location: a relative path would resolve against
-* the host process's unpredictable cwd. `~` is expanded for convenience and
-* the result is normalized; the root itself is rejected because workspace
-* directories are appended to it.
-*
-* @param raw - untrusted panel value.
-* @param home - home directory seam (tests pin it; production uses `homedir()`).
-* @returns the normalized absolute path, or a user-facing message.
+* @module dsh-channels/session/isolation
 */
-function normalizeWorkspaceBaseDir(raw, home = homedir()) {
-	if (typeof raw !== "string") return {
-		ok: false,
-		message: "必须是字符串"
-	};
-	const trimmed = raw.trim();
-	if (trimmed === "") return {
-		ok: false,
-		message: "不能为空"
-	};
-	if (trimmed.length > MAX_BASE_DIR_LENGTH) return {
-		ok: false,
-		message: `路径长度不得超过 ${MAX_BASE_DIR_LENGTH} 个字符`
-	};
-	if (/[\u0000-\u001f\u007f]/.test(trimmed)) return {
-		ok: false,
-		message: "包含非法控制字符"
-	};
-	let expanded = trimmed;
-	if (expanded === "~") expanded = home;
-	else if (expanded.startsWith("~/") || expanded.startsWith("~\\")) expanded = path.join(home, expanded.slice(2));
-	if (!path.isAbsolute(expanded)) return {
-		ok: false,
-		message: "必须是绝对路径（例如 /Users/you/.dsh/dsh-channels/workspaces）"
-	};
-	const normalized = path.resolve(expanded);
-	if (path.parse(normalized).root === normalized) return {
-		ok: false,
-		message: "不能使用文件系统根目录"
-	};
+/** Resolve the placement capabilities from the host context (all optional). */
+function placementServices(ctx) {
+	const get = (name) => ctx.get?.(name);
 	return {
-		ok: true,
-		value: normalized
+		workingDirectory: get("workingDirectory"),
+		worktrees: get("worktrees")
 	};
 }
-/**
-* Materialize one panel-supplied workspace root and prove it is usable.
-*
-* Called when the panel saves `baseDir` so an unusable location fails at save
-* time instead of surfacing later as "会话创建失败" inside a Feishu chat.
-* The directory is created here (the same `mkdir -p` the first session would
-* perform); an existing non-directory is refused.
-*
-* @returns an error message, or `undefined` when the directory is writable.
-*/
-async function prepareWorkspaceBaseDir(dir) {
-	try {
-		await mkdir(dir, { recursive: true });
-	} catch (error) {
-		return `无法创建工作区目录：${String(error)}`;
-	}
-	try {
-		if (!(await stat(dir)).isDirectory()) return "该路径已存在但不是目录";
-	} catch (error) {
-		return `无法读取工作区目录：${String(error)}`;
-	}
+/** Whether the workspace directory is itself a Git working tree. */
+async function workspaceHasGitRepository(workspacePath) {
 	try {
-		await access(dir, constants.W_OK);
+		const info = await stat(path.join(workspacePath, ".git"));
+		return info.isDirectory() || info.isFile();
 	} catch {
-		return "工作区目录不可写";
+		return false;
 	}
 }
-function safeSegment(raw, what) {
-	const segment = raw.replace(/^\/+|\/+$/g, "");
-	if (!SAFE_SEGMENT.test(segment) || segment === "." || segment === "..") throw new Error(`dsh-channels: unsafe ${what} for workspace path: ${JSON.stringify(raw)}`);
-	return segment;
+/**
+* Pick the isolation mode for one topic. `auto` upgrades to a worktree only
+* when both the capability and a Git repository are present; an explicit
+* `worktree` preference still falls back (with a warning) when unavailable.
+*/
+async function chooseTopicMode(services, config, workspacePath, warn) {
+	const requested = config.topicIsolation;
+	if (requested === "subdir") return "subdir";
+	if (!(services.workingDirectory !== void 0 && services.worktrees !== void 0)) {
+		if (requested === "worktree") warn("dsh-channels: topicIsolation=worktree needs the workingDirectory and worktrees host services; using a plain topic directory");
+		return "subdir";
+	}
+	if (requested === "worktree") return "worktree";
+	return await workspaceHasGitRepository(workspacePath) ? "worktree" : "subdir";
 }
 /**
-* Stable, filesystem-safe token for one Feishu conversation: a real topic uses
-* its thread id, while a degraded chat-scoped conversation uses the Session id
-* that owns it (there is no topic boundary to key on).
+* Decide how a new Session is placed and materialize everything that must
+* exist before the Session is created.
+*
+* The returned `cwd` is the header cwd: the workspace root when the runtime
+* can switch directories (so the Session is grouped under the user's project),
+* otherwise the topic directory itself.
 */
-function topicTokenFor(routeKey, kind, sessionId) {
-	return kind === "thread" ? safeSegment(routeKey, "route key") : safeSegment(sessionId, "session id");
+async function planTopic(services, config, workspacePath, topicToken, warn) {
+	const mode = await chooseTopicMode(services, config, workspacePath, warn);
+	if (services.workingDirectory !== void 0) {
+		const subdir = mode === "subdir" ? topicDirFor(workspacePath, topicToken) : void 0;
+		if (subdir !== void 0) await mkdir(subdir, { recursive: true });
+		return {
+			mode,
+			cwd: workspacePath,
+			...subdir === void 0 ? {} : { subdir },
+			switchable: true
+		};
+	}
+	const subdir = topicDirFor(workspacePath, topicToken);
+	await mkdir(subdir, { recursive: true });
+	return {
+		mode: "subdir",
+		cwd: subdir,
+		subdir,
+		switchable: false
+	};
+}
+/** Enter the planned topic directory once the Session (and its Agent) exists. */
+async function enterTopic(services, agent, plan, workspacePath, topicToken, warn) {
+	if (plan.mode === "worktree" && services.worktrees !== void 0) try {
+		const created = await services.worktrees.create(agent, { name: worktreeBranchFor(topicToken) });
+		return {
+			sessionDir: created.path,
+			worktreeBranch: created.branch
+		};
+	} catch (error) {
+		warn("dsh-channels: creating a worktree for topic %s failed, using a plain topic directory instead: %s", topicToken, String(error));
+	}
+	const dir = plan.subdir ?? topicDirFor(workspacePath, topicToken);
+	await mkdir(dir, { recursive: true });
+	if (plan.switchable) await alignWorkingDirectory(services, agent, dir, warn);
+	return { sessionDir: dir };
 }
 /**
-* Deterministic workspace directory for one Feishu topic: every route gets its
-* own workspace below its (user × chat) grouping directory.
-*
-* - p2p:   `<baseDir>/topics/p2p/<open_id>/<topic>/`
-* - group: `<baseDir>/topics/groups/<chat_id>/<open_id>/<topic>/`
+* Align one live Session with its recorded topic directory: make sure the
+* directory exists, recreate it (or a fresh worktree) when it disappeared,
+* and restore the effective working directory the route expects.
 *
-* A separate `topics/` root keeps new workspaces out of the legacy (user ×
-* chat) workspace directories left by older versions, so cleaning one can
-* never delete the other.
-*/
-function workspacePathFor(baseDir, chatType, chatId, senderOpenId, topicToken) {
-	const chat = safeSegment(chatId, "chatId");
-	const user = safeSegment(senderOpenId, "senderOpenId");
-	const topic = safeSegment(topicToken, "topic token");
-	return chatType === "p2p" ? path.join(baseDir, "topics", "p2p", user, topic) : path.join(baseDir, "topics", "groups", chat, user, topic);
-}
-/**
-* Staging directory for attachments that arrive before their topic (and so
-* its workspace) exists. Not a registered workspace: files move into the real
-* workspace as soon as the first Session of that topic is created.
+* The returned placement may carry a new directory/branch after recovery; the
+* caller persists it back into the route record.
 */
-function stagingPathFor(baseDir, chatType, chatId, senderOpenId) {
-	const chat = safeSegment(chatId, "chatId");
-	const user = safeSegment(senderOpenId, "senderOpenId");
-	return path.join(baseDir, "_staging", chatType, chat, user);
+async function restoreTopicDir(services, agent, input, warn) {
+	const { sessionDir, worktreeBranch } = input;
+	if (await isDirectory(sessionDir)) {
+		await alignWorkingDirectory(services, agent, sessionDir, warn);
+		return worktreeBranch === void 0 ? { sessionDir } : {
+			sessionDir,
+			worktreeBranch
+		};
+	}
+	if (worktreeBranch !== void 0 && services.worktrees !== void 0 && services.workingDirectory !== void 0) try {
+		const created = await services.worktrees.create(agent, { name: `${worktreeBranch}-r${randomUUID().slice(0, 8)}` });
+		return {
+			sessionDir: created.path,
+			worktreeBranch: created.branch
+		};
+	} catch (error) {
+		warn("dsh-channels: recreating the worktree for session %s failed, using a plain directory: %s", agent.id, String(error));
+	}
+	await mkdir(sessionDir, { recursive: true });
+	await alignWorkingDirectory(services, agent, sessionDir, warn);
+	return { sessionDir };
 }
-/** Human-friendly workspace title shown in the DSH workspace list. */
-function workspaceTitleFor(chatType, chatId, senderOpenId, topicToken) {
-	const base = chatType === "p2p" ? `飞书私聊 · ${senderOpenId}` : `飞书群聊 · ${chatId} · ${senderOpenId}`;
-	return topicToken === void 0 ? base : `${base} · ${topicToken}`;
+/** Best-effort check used only for placement decisions, never for security. */
+async function isDirectory(dir) {
+	try {
+		return (await stat(dir)).isDirectory();
+	} catch {
+		return false;
+	}
 }
-/**
-* Ensure one topic's workspace directory exists and is registered with the
-* host's workspace registry. Idempotent: repeated calls return the same record.
-*/
-async function ensureWorkspace(ctx, baseDir, chatType, chatId, senderOpenId, topicToken) {
-	const dir = workspacePathFor(baseDir, chatType, chatId, senderOpenId, topicToken);
-	await mkdir(dir, { recursive: true });
-	return ctx.workspaceRegistry.create(dir, workspaceTitleFor(chatType, chatId, senderOpenId, topicToken));
+/** Point the Session's effective working directory at `dir`. */
+async function alignWorkingDirectory(services, agent, dir, warn) {
+	const workingDirectory = services.workingDirectory;
+	if (workingDirectory === void 0) return;
+	try {
+		if (workingDirectory.get(agent.session) === dir) return;
+		await workingDirectory.set(agent, dir);
+	} catch (error) {
+		warn("dsh-channels: switching session %s to its topic directory failed: %s", agent.id, String(error));
+	}
 }
 //#endregion
 //#region src/session/manager.ts
@@ -4024,10 +4328,12 @@ var SessionManager = class {
 	}
 	/**
 	* Create the root agent for one freshly routed session and register it live.
-	* The caller owns the workspace attachment and the failure card.
+	* `cwd` is the Session header cwd (the user workspace when the deployment can
+	* switch directories). The caller owns placement, the workspace attachment,
+	* the attachment guidance, and the failure card.
 	*/
 	async createSession(sessionId, cwd, agentOptions = this.agentOptions()) {
-		const composition = await this.presetComposition(void 0, true, attachmentsDir(cwd));
+		const composition = await this.presetComposition(void 0, true);
 		const handle = await this.deps.ctx.agents.create({
 			sessionId,
 			meta: {
@@ -4045,6 +4351,20 @@ var SessionManager = class {
 		return handle;
 	}
 	/**
+	* Register the attachment-directory guidance for one Session. Called after
+	* the effective working directory is known (a worktree checkout path is
+	* only returned once the worktree exists), so the prompt section can name
+	* the absolute directory. Best-effort: a missing system-prompt service
+	* (headless) is a no-op and a late registration never blocks the turn.
+	*/
+	async mountGuidance(agent, directory) {
+		try {
+			await mountChannelGuidance(agent.ctx, attachmentsDir(directory));
+		} catch (error) {
+			this.deps.warn("dsh-channels: mounting attachment guidance for session %s failed: %s", agent.id, String(error));
+		}
+	}
+	/**
 	* Live agent for a route: this plugin's own → a foreign live agent (borrow)
 	* → a serialized cold resume.
 	*
@@ -4080,7 +4400,7 @@ var SessionManager = class {
 	async resume(record) {
 		const sessionId = record.sessionId;
 		try {
-			const composition = await this.presetComposition(void 0, true, attachmentsDir(record.workspacePath));
+			const composition = await this.presetComposition(void 0, true);
 			const handle = await this.deps.ctx.agents.resume({
 				resumeSessionId: sessionId,
 				agentOptions: this.agentOptions(),
@@ -4091,6 +4411,7 @@ var SessionManager = class {
 				throw new Error("dsh-channels: session resume aborted by shutdown");
 			}
 			this.requestPolicy(handle.agent);
+			await this.mountGuidance(handle.agent, sessionDirOf(record));
 			const liveAgent = {
 				agent: handle.agent,
 				handle
@@ -4124,33 +4445,56 @@ var SessionManager = class {
 		controller.sync(agent.session.snapshotEvents());
 		return controller;
 	}
-	/** Create, workspace-attach, and atomically publish one renewed route. */
+	/**
+	* Create, place, workspace-attach, and atomically publish one renewed route.
+	*
+	* A renewal keeps the topic's working directory: the new Session is created
+	* with the user workspace as its header cwd (so it stays grouped under the
+	* project) and then re-entered into the same topic directory or worktree.
+	*/
 	async renew(record, oldLive) {
 		const sessionId = randomUUID();
 		const preset = this.effectivePreset(oldLive.agent.session);
-		const composition = await this.presetComposition(preset, false, attachmentsDir(record.workspacePath));
-		const workspace = await this.deps.ctx.workspaceRegistry.create(record.workspacePath, workspaceTitleFor(record.chatType, record.chatId, record.senderOpenId, record.kind === "thread" ? record.key : record.sessionId));
+		const composition = await this.presetComposition(preset, false);
+		const services = placementServices(this.deps.ctx);
+		const switchable = services.workingDirectory !== void 0;
+		const workspacePath = record.workspacePath;
+		const workspace = await this.deps.ctx.workspaceRegistry.create(workspacePath, workspaceTitleFor(record.chatType, record.chatId, record.senderOpenId));
 		let newHandle;
 		let attached = false;
 		try {
 			newHandle = await this.deps.ctx.agents.create({
 				sessionId,
 				meta: {
-					cwd: record.workspacePath,
+					cwd: switchable ? workspacePath : sessionDirOf(record),
 					...composition.agentPreset === void 0 ? {} : { agentPreset: composition.agentPreset }
 				},
 				agentOptions: { ...oldLive.agent.options },
 				setup: composition.setup
 			});
 			this.requestPolicy(newHandle.agent);
-			await workspace.attachSession(sessionId);
-			attached = true;
+			const placement = await restoreTopicDir(services, newHandle.agent, {
+				workspacePath,
+				sessionDir: sessionDirOf(record),
+				...record.worktreeBranch === void 0 ? {} : { worktreeBranch: record.worktreeBranch }
+			}, this.deps.warn.bind(this.deps));
+			if (switchable) {
+				await workspace.attachSession(sessionId);
+				attached = true;
+			}
+			await this.mountGuidance(newHandle.agent, placement.sessionDir);
 			const createdAt = newHandle.agent.session.header.createdAt;
-			const current = {
+			const base = {
 				...record,
 				sessionId,
 				sessionHistory: appendSessionHistory(record, sessionId, createdAt),
-				lastActivityAt: Date.now()
+				lastActivityAt: Date.now(),
+				sessionDir: placement.sessionDir
+			};
+			delete base.worktreeBranch;
+			const current = placement.worktreeBranch === void 0 ? base : {
+				...base,
+				worktreeBranch: placement.worktreeBranch
 			};
 			await this.deps.persistRoute(record.key, current);
 			this.live.set(sessionId, {
@@ -4194,13 +4538,16 @@ var SessionManager = class {
 	* resumes. The id resolves BEFORE the session exists because the session
 	* boundary snapshots `meta` before asynchronous setup begins; mounting stays
 	* inside `setup`, where a failure rolls the whole creation back.
+	*
+	* The attachment guidance is mounted later through {@link mountGuidance},
+	* because a Git worktree's checkout path only exists after the Agent (and so
+	* the worktree) has been created.
 	*/
-	async presetComposition(requestedPreset = this.deps.config.agentPreset, useRosterDefault = true, attachmentsDir) {
+	async presetComposition(requestedPreset = this.deps.config.agentPreset, useRosterDefault = true) {
 		const presets = this.deps.ctx.get?.("agentPresets");
 		const channelCommandsOnly = async (agentCtx) => {
 			this.mountRequestPolicy(agentCtx);
 			await mountChannelCommands(agentCtx);
-			await mountChannelGuidance(agentCtx, attachmentsDir);
 		};
 		if (presets === void 0 || requestedPreset === void 0 && !useRosterDefault) return { setup: channelCommandsOnly };
 		const resolved = await presets.resolve(requestedPreset);
@@ -4210,7 +4557,6 @@ var SessionManager = class {
 				this.mountRequestPolicy(agentCtx);
 				await presets.mount(agentCtx, resolved.id);
 				await mountChannelCommands(agentCtx);
-				await mountChannelGuidance(agentCtx, attachmentsDir);
 			}
 		};
 	}
@@ -4595,7 +4941,7 @@ var InboundRouter = class {
 				attachmentOnly: true,
 				text: ""
 			};
-			const directory = record === void 0 ? stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId) : attachmentsDir(record.workspacePath);
+			const directory = record === void 0 ? stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId) : attachmentsDir(sessionDirOf(record));
 			return await this.attachments.archive(msg, directory);
 		});
 	}
@@ -4673,11 +5019,13 @@ var InboundRouter = class {
 		const typingId = await typingPromise;
 		const key = sent.degraded || sent.threadId === void 0 ? chatKey : sent.threadId;
 		const kind = sent.degraded || sent.threadId === void 0 ? "chat" : "thread";
-		let workspace;
-		try {
-			workspace = await ensureWorkspace(this.ctx, this.config.baseDir, msg.chatType, msg.chatId, msg.senderId, topicTokenFor(key, kind, sessionId));
-			await adoptStagedAttachments(stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId), workspace.path);
-		} catch (error) {
+		const topicToken = topicTokenFor(key, kind, sessionId);
+		const services = placementServices(this.ctx);
+		const warn = (message, ...args) => {
+			this.ctx.logger?.warn?.(message, ...args);
+		};
+		/** Patch the streaming card to its terminal creation-failure state. */
+		const failCreation = async (error) => {
 			this.repair.clear(sent.messageId);
 			await this.delivery.requireChannel().updateCard(sent.messageId, buildCard({
 				phase: "done",
@@ -4685,6 +5033,14 @@ var InboundRouter = class {
 				body: `会话创建失败：${String(error)}`,
 				stats: { ...initialStats }
 			})).catch(() => {});
+		};
+		let workspace;
+		let plan;
+		try {
+			workspace = await ensureWorkspace(this.ctx, this.config.baseDir, msg.chatType, msg.chatId, msg.senderId);
+			plan = await planTopic(services, this.config, workspace.path, topicToken, warn);
+		} catch (error) {
+			await failCreation(error);
 			throw error;
 		}
 		await this.repair.write({
@@ -4701,21 +5057,23 @@ var InboundRouter = class {
 			attempts: 0
 		});
 		let handle;
+		let placement;
 		try {
-			handle = await this.sessions.createSession(sessionId, workspace.path);
+			handle = await this.sessions.createSession(sessionId, plan.cwd);
+			placement = await enterTopic(services, handle.agent, plan, workspace.path, topicToken, warn);
+			if (plan.cwd === workspace.path) Promise.resolve(workspace.attachSession(sessionId)).catch((error) => {
+				warn("dsh-channels: attaching initial session %s to workspace failed: %s", sessionId, String(error));
+			});
+			await adoptStagedAttachments(stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId), placement.sessionDir).catch((error) => {
+				warn("dsh-channels: adopting staged attachments failed: %s", String(error));
+			});
+			await this.sessions.mountGuidance(handle.agent, placement.sessionDir);
 		} catch (error) {
-			this.repair.clear(sent.messageId);
-			await this.delivery.requireChannel().updateCard(sent.messageId, buildCard({
-				phase: "done",
-				reasoning: "",
-				body: `会话创建失败：${String(error)}`,
-				stats: { ...initialStats }
-			})).catch(() => {});
+			await handle?.dispose().catch(() => {});
+			await failCreation(error);
 			throw error;
 		}
-		Promise.resolve(workspace.attachSession(sessionId)).catch((error) => {
-			this.ctx.logger?.warn?.("dsh-channels: attaching initial session %s to workspace failed: %s", sessionId, String(error));
-		});
+		if (handle === void 0 || placement === void 0) throw new Error("dsh-channels: session creation completed without a handle");
 		const createdAt = handle.agent.session.header.createdAt;
 		const record = {
 			key,
@@ -4725,6 +5083,8 @@ var InboundRouter = class {
 			chatType: msg.chatType,
 			senderOpenId: msg.senderId,
 			workspacePath: workspace.path,
+			sessionDir: placement.sessionDir,
+			...placement.worktreeBranch === void 0 ? {} : { worktreeBranch: placement.worktreeBranch },
 			cardMessageId: sent.messageId,
 			createdAt,
 			lastActivityAt: createdAt,
@@ -4740,16 +5100,37 @@ var InboundRouter = class {
 	}
 	async continueSession(msg, record, content) {
 		if (!this.access.ownsRoute(msg, record)) return;
-		await adoptStagedAttachments(stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId), record.workspacePath).catch((error) => {
-			this.ctx.logger?.warn?.("dsh-channels: adopting staged attachments failed: %s", String(error));
-		});
+		const services = placementServices(this.ctx);
+		const warn = (message, ...args) => {
+			this.ctx.logger?.warn?.(message, ...args);
+		};
 		const typingPromise = this.delivery.requireChannel().addReaction(msg.messageId, "Typing").catch(() => void 0);
 		const live = await this.sessions.ensureLive(record);
-		const sent = await this.delivery.replyFirstCard(msg, initialStreamingCard(record.sessionId));
+		const placement = await restoreTopicDir(services, live.agent, {
+			workspacePath: record.workspacePath,
+			sessionDir: sessionDirOf(record),
+			...record.worktreeBranch === void 0 ? {} : { worktreeBranch: record.worktreeBranch }
+		}, warn);
+		let current = record;
+		if (placement.sessionDir !== sessionDirOf(record) || placement.worktreeBranch !== record.worktreeBranch) {
+			current = {
+				...record,
+				sessionDir: placement.sessionDir
+			};
+			delete current.worktreeBranch;
+			if (placement.worktreeBranch !== void 0) current = {
+				...current,
+				worktreeBranch: placement.worktreeBranch
+			};
+		}
+		await adoptStagedAttachments(stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId), placement.sessionDir).catch((error) => {
+			this.ctx.logger?.warn?.("dsh-channels: adopting staged attachments failed: %s", String(error));
+		});
+		const sent = await this.delivery.replyFirstCard(msg, initialStreamingCard(current.sessionId));
 		const typingId = await typingPromise;
 		await this.repair.write({
 			key: sent.messageId,
-			sessionId: record.sessionId,
+			sessionId: current.sessionId,
 			chatId: msg.chatId,
 			triggerMessageId: msg.messageId,
 			reactionId: typingId,
@@ -4760,8 +5141,8 @@ var InboundRouter = class {
 			startedAt: Date.now(),
 			attempts: 0
 		});
-		await this.routes.put(record.key, {
-			...record,
+		await this.routes.put(current.key, {
+			...current,
 			cardMessageId: sent.messageId,
 			lastActivityAt: Date.now()
 		});
@@ -5367,7 +5748,7 @@ function statusExtrasElements(extras) {
 	if (extras === void 0) return [];
 	const lines = [];
 	if (extras.permissionPreset !== void 0) lines.push(`**权限预设**：\`${escapeInlineCode(extras.permissionPreset)}\``);
-	if (extras.workspacePath !== void 0) lines.push(`**工作区**：\`${escapeInlineCode(extras.workspacePath)}\``);
+	if (extras.sessionDir !== void 0) lines.push(`**会话目录**：\`${escapeInlineCode(extras.sessionDir)}\``);
 	if (extras.uptimeMs !== void 0) lines.push(`**插件运行时长**：${fmtUptime(extras.uptimeMs)}`);
 	if (extras.liveAgents !== void 0 || extras.routeCount !== void 0) {
 		const parts = [];
@@ -5388,30 +5769,43 @@ function fmtUptime(ms) {
 	const hours = Math.floor(totalSeconds / 3600);
 	return hours === 0 ? `${minutes} 分` : `${hours} 小时 ${minutes} 分`;
 }
-/** Validate the Session header cwd against the plugin's durable route. */
-function resolveWorkDir(headerCwd, routeWorkspacePath) {
+/**
+* Validate the Session header cwd against the plugin's durable route and
+* return the Session's effective working directory.
+*
+* The header cwd is normally the workspace root (the Session stays grouped
+* under the user's project while working in a per-topic directory). In the
+* degraded placement used when the host exposes no `workingDirectory` service,
+* the header cwd is the topic directory itself.
+*/
+function resolveWorkDir(headerCwd, route) {
 	if (headerCwd === void 0 || headerCwd === "" || !path.isAbsolute(headerCwd)) return {
 		kind: "missing",
 		text: "当前 Session header 未记录可用的绝对工作目录；请检查 Session 创建或恢复配置。"
 	};
-	if (!path.isAbsolute(routeWorkspacePath)) return {
+	if (!path.isAbsolute(route.workspacePath)) return {
 		kind: "missing",
-		text: "当前飞书路由未记录可用的绝对工作目录；请检查路由持久化状态。"
+		text: "当前飞书路由未记录可用的工作区目录；请检查路由持久化状态。"
 	};
-	if (headerCwd !== routeWorkspacePath) return {
+	if (route.sessionDir !== void 0 && !path.isAbsolute(route.sessionDir)) return {
+		kind: "missing",
+		text: "当前飞书路由未记录可用的会话目录；请检查路由持久化状态。"
+	};
+	const expected = route.sessionDir ?? route.workspacePath;
+	if (headerCwd !== route.workspacePath && headerCwd !== expected) return {
 		kind: "mismatch",
 		text: "Session header 与飞书路由记录的工作目录不一致；为避免返回错误目录，已拒绝显示。"
 	};
 	return {
 		kind: "success",
-		path: headerCwd
+		path: expected
 	};
 }
-/** Render one verified absolute workspace path. */
-function buildWorkDirCard(sessionId, workspacePath) {
+/** Render one verified absolute working directory. */
+function buildWorkDirCard(sessionId, sessionDir) {
 	return standaloneCard("**📁 当前工作目录**", [{
 		tag: "markdown",
-		content: `\`${escapeInlineCode(workspacePath)}\``
+		content: `\`${escapeInlineCode(sessionDir)}\``
 	}, {
 		tag: "markdown",
 		content: sessionId,
@@ -5422,7 +5816,7 @@ function buildWorkDirCard(sessionId, workspacePath) {
 function buildRenewCard(input) {
 	return standaloneCard("**🔄 Session 已续建**", [{
 		tag: "markdown",
-		content: `**旧 Session**：${input.previousSessionId}\n**新 Session**：${input.currentSessionId}\n**复用工作区**：\`${escapeInlineCode(input.workspacePath)}\``
+		content: `**旧 Session**：${input.previousSessionId}\n**新 Session**：${input.currentSessionId}\n**复用目录**：\`${escapeInlineCode(input.sessionDir)}\``
 	}, {
 		tag: "markdown",
 		content: "旧 Session 及其日志仍由 Harness 保留。",
@@ -5562,7 +5956,7 @@ async function createLogicalSessionExport(session, options = {}) {
 * console can confirm which build of the activity status line is loaded.
 * Bump on every behavior change to this feature.
 */
-const ACTIVITY_BUILD_MARKER = "activity-status-v6";
+const ACTIVITY_BUILD_MARKER = "activity-status-v7";
 /** Hard cap on the activity line so it can never threaten the card budget. */
 const ACTIVITY_MAX_CHARS = 64;
 /** Trim an activity line to `ACTIVITY_MAX_CHARS` (ellipsis counts as one char). */
@@ -5639,7 +6033,6 @@ var TurnStreamer = class {
 			reasoning: "",
 			header: void 0,
 			lastUsage: void 0,
-			failure: void 0,
 			cards: [{
 				messageId: cardMessageId,
 				body: "",
@@ -5657,6 +6050,8 @@ var TurnStreamer = class {
 			finalized: false,
 			disposed: false,
 			turnStartedAt: Date.now(),
+			reasoningSince: void 0,
+			reasoningMs: 0,
 			toolActivity: void 0,
 			workflowRuns: /* @__PURE__ */ new Map(),
 			workflowEndStatus: void 0,
@@ -5823,12 +6218,14 @@ var TurnStreamer = class {
 		if (state === void 0 || state.disposed) return;
 		switch (frame.type) {
 			case "start":
+				this.closeReasoning(state);
 				state.attempts.set(frame.attemptId, this.attemptMark(state));
 				if (state.turn === void 0) state.turn = frame.turn;
 				break;
 			case "chunk": {
 				const chunk = frame.chunk;
 				if (chunk.type === "text-delta") {
+					if (chunk.text !== "") this.closeReasoning(state);
 					const last = state.cards[state.cards.length - 1];
 					if (last !== void 0 && !last.frozen && chunk.text !== "") {
 						last.body += chunk.text;
@@ -5836,12 +6233,14 @@ var TurnStreamer = class {
 						this.markDirty(session.id, state);
 					}
 				} else if (chunk.type === "reasoning-delta" && chunk.text !== "") {
+					if (state.reasoningSince === void 0) state.reasoningSince = Date.now();
 					state.reasoning += chunk.text;
 					this.markDirty(session.id, state);
 				}
 				break;
 			}
 			case "end": {
+				this.closeReasoning(state);
 				const mark = state.attempts.get(frame.attemptId);
 				state.attempts.delete(frame.attemptId);
 				if (frame.outcome.kind === "abandoned" && mark !== void 0) {
@@ -5857,9 +6256,17 @@ var TurnStreamer = class {
 		return {
 			cardCount: state.cards.length,
 			bodyLengths: state.cards.map((card) => card.body.length),
-			reasoningLength: state.reasoning.length
+			reasoningLength: state.reasoning.length,
+			reasoningMs: state.reasoningMs,
+			reasoningSince: state.reasoningSince
 		};
 	}
+	/** Close an open reasoning phase, accumulating its wall-clock time. */
+	closeReasoning(state, now = Date.now()) {
+		if (state.reasoningSince === void 0) return;
+		state.reasoningMs += Math.max(0, now - state.reasoningSince);
+		state.reasoningSince = void 0;
+	}
 	/**
 	* Drop one abandoned attempt's deltas. The attempt's text is a contiguous
 	* suffix of the logical body: segments created during the attempt are
@@ -5882,6 +6289,8 @@ var TurnStreamer = class {
 			tail.dirty = true;
 		}
 		state.reasoning = state.reasoning.slice(0, mark.reasoningLength);
+		state.reasoningMs = mark.reasoningMs;
+		state.reasoningSince = mark.reasoningSince;
 	}
 	markDirty(sessionId, state) {
 		if (state.disposed) return;
@@ -5915,7 +6324,8 @@ var TurnStreamer = class {
 			contextTokens: context?.contextTokens,
 			contextWindow: header === void 0 ? void 0 : context?.contextWindow ?? projected?.contextWindow,
 			model: header?.model,
-			effort: header?.effort
+			effort: header?.effort,
+			reasoningMs: state.reasoning === "" ? void 0 : state.reasoningMs
 		};
 	}
 	/**
@@ -5983,10 +6393,10 @@ var TurnStreamer = class {
 	*     an elapsed counter so the card never sits silently.
 	* Once the turn is finalized, the line switches to the SETTLED form
 	* (workflow conclusion + finished-subagent summary) — the final card keeps
-	* the delegation status; only the tool line disappears.
+	* the delegation status; only the tool line disappears. A failed turn shows
+	* its diagnostic once, in the body: the status line never repeats it.
 	*/
 	delegationLine(state, now) {
-		if (state.failure !== void 0) return clipActivity(`🔴 本轮运行失败${state.failure.code === void 0 ? "" : ` · ${state.failure.code}`}`);
 		if (state.finalized) return this.settledLine(state);
 		let latest;
 		for (const run of state.workflowRuns.values()) if (latest === void 0 || run.startedAt > latest.startedAt) latest = run;
@@ -6062,7 +6472,14 @@ var TurnStreamer = class {
 			this.scheduleHeartbeat(sessionId, state);
 		}, this.heartbeatMs);
 	}
-	cardState(sessionId, state, body) {
+	/**
+	* Snapshot one card. `active` is true for the card currently streaming:
+	* only that card renders the transient activity lines, so frozen segment
+	* cards never repeat a stale tool/delegation line. Both lines are still
+	* recomputed (and remembered) on every snapshot so heartbeat/transition
+	* logging stays accurate.
+	*/
+	cardState(sessionId, state, body, active = true) {
 		const now = Date.now();
 		const status = this.delegationLine(state, now);
 		if (status !== state.status) {
@@ -6080,8 +6497,8 @@ var TurnStreamer = class {
 			phase: state.phase,
 			reasoning: state.reasoning,
 			body,
-			status: state.status,
-			tool: state.tool,
+			status: active ? state.status : "",
+			tool: active ? state.tool : "",
 			stats: this.statsFor(sessionId, state)
 		};
 	}
@@ -6106,10 +6523,7 @@ var TurnStreamer = class {
 			const index = state.cards.length - 1;
 			const card = state.cards[index];
 			if (card === void 0 || card.frozen || card.mode === "text") return;
-			const options = index === 0 ? {} : {
-				panel: false,
-				segment: index + 1
-			};
+			const options = segmentCardOptions(index);
 			const split = segmentCardContent(this.cardState(sessionId, state, card.body), options);
 			if (split.head === "") return;
 			if (split.tail === "") {
@@ -6155,10 +6569,7 @@ var TurnStreamer = class {
 		const next = (this.segmentChains.get(sessionId) ?? Promise.resolve()).then(async () => {
 			let lastError;
 			for (let attempt = 0; attempt < 3; attempt++) try {
-				const snapshot = buildCard(this.cardState(sessionId, state, card.body), {
-					panel: false,
-					segment: index + 1
-				});
+				const snapshot = buildCard(this.cardState(sessionId, state, card.body, index === state.cards.length - 1), segmentCardOptions(index));
 				const delivery = await this.hooks.sendSegmentCard(sessionId, index + 1, snapshot, card.body);
 				card.sending = false;
 				card.messageId = delivery.messageId;
@@ -6197,11 +6608,8 @@ var TurnStreamer = class {
 		if (!force && !card.dirty && !turnDirty) return;
 		if (!force && card.nextRetryAt > now) return;
 		card.dirty = false;
-		const options = index === 0 ? {} : {
-			panel: false,
-			segment: index + 1
-		};
-		const snapshot = buildCard(this.cardState(sessionId, state, card.body), options);
+		const options = segmentCardOptions(index);
+		const snapshot = buildCard(this.cardState(sessionId, state, card.body, index === state.cards.length - 1), options);
 		this.channel.updateCard(card.messageId, snapshot).catch((error) => {
 			card.dirty = true;
 			card.failures++;
@@ -6221,15 +6629,15 @@ var TurnStreamer = class {
 	finalize(sessionId, state, failure) {
 		if (state.finalized) return;
 		state.finalized = true;
-		state.failure = failure;
 		state.phase = failure === void 0 ? "done" : "error";
+		this.closeReasoning(state);
 		if (failure !== void 0) {
 			const code = failure.code === void 0 ? "" : `\n\n错误码：\`${failure.code}\``;
 			const notice = `❌ **本轮运行失败**\n\n${failure.message}${code}`;
 			const tail = state.cards[state.cards.length - 1];
 			if (tail !== void 0) if (tail.mode === "text" || tail.failed) state.cards.push(this.freshSegment(notice));
 			else {
-				tail.body = tail.body.trim() === "" ? notice : `${tail.body}\n\n---\n\n${notice}`;
+				tail.body = tail.body.trim() === "" ? notice : `${tail.body}\n\n${notice}`;
 				tail.dirty = true;
 			}
 		}
@@ -6281,6 +6689,10 @@ function turnFailure(reason) {
 *  - p2p:   one workspace per (bot, user), all of that user's sessions inside;
 *  - group: one workspace per (chat, user), sessions grouped per user.
 *
+* Every topic's Session works in its own directory inside that workspace
+* (`topics/<token>` or a Git worktree), so topics never mix files while the
+* workspace list grows with users instead of conversations.
+*
 * Routing model:
 *  - `thread_id` → bound session (no @ needed inside an owned topic);
 *  - degraded chat-scoped keys when Feishu refuses topic replies;
@@ -6460,13 +6872,21 @@ var FeishuService = class {
 	started = false;
 	/** Epoch ms when `start()` completed (uptime for `/status`). */
 	startedAt;
-	/** Last failed `boot()` message, surfaced in the Web settings panel. */
+	/** Last failed connection attempt, surfaced in the Web settings panel. */
 	lastStartError;
+	/** Whether both Feishu application credentials currently resolve. */
+	configured = false;
+	/** Names of the missing credential references (never their values). */
+	missingConfigItems = [];
+	/** Guards the panel's explicit connect action (distinct from a restart). */
+	connecting = false;
 	/** Effective config captured at the last successful connect (restart-pending diff). */
 	runningConfig;
 	/** Guards overlapping panel-triggered reconnects. */
 	restarting = false;
 	unlisten;
+	/** Disposers for host-scoped listeners registered by `start()`. */
+	unlistenHost = [];
 	/** Periodic route-GC timer (unref'd; only armed when `routeTtlMs > 0`). */
 	gcTimer;
 	/** Periodic workspace-retention timer (only armed when auto cleanup is on). */
@@ -6565,24 +6985,82 @@ var FeishuService = class {
 		});
 	}
 	/**
-	* Load the Web overlay, then open the channel. Startup errors are recorded
-	* for the settings panel and the partial service is torn down before the
-	* error is rethrown (the plugin fiber still fails the same way).
+	* Load the Web overlay and open the long connection when — and only when —
+	* the Feishu application credentials are complete.
+	*
+	* An incomplete configuration is a normal state, not an error: the plugin
+	* stays loaded so the Web settings panel can guide the user through the
+	* credentials form, and no connection is attempted. A failed connection
+	* attempt is recorded for the panel instead of failing the plugin fiber.
 	*/
 	async boot() {
+		if (this.connecting || this.restarting) return;
+		this.connecting = true;
 		try {
 			await this.loadOverlay();
+			await this.refreshReadiness();
+			if (!this.configured) {
+				this.lastStartError = void 0;
+				this.runningConfig = void 0;
+				this.ctx.logger?.info?.("dsh-channels: 飞书应用凭据未配置完整（缺少 %s），本次不连接飞书；请在 Web 设置面板 → 飞书渠道中配置，保存后会自动连接", this.missingConfigItems.join("、"));
+				return;
+			}
+			await this.openConnection();
+		} catch {} finally {
+			this.connecting = false;
+		}
+	}
+	/**
+	* Refresh the cached configuration readiness from the credentials seam.
+	* Only presence is checked (describe/resolve), never values; the secrets
+	* themselves are resolved by `start()` when a connection is opened.
+	*/
+	async refreshReadiness() {
+		const states = await this.credentialStates();
+		const missing = [];
+		if (!states.appId.configured) missing.push(`${this.config.appId}（飞书 App ID）`);
+		if (!states.appSecret.configured) missing.push(`${this.config.appSecret}（飞书 App Secret）`);
+		this.missingConfigItems = missing;
+		this.configured = missing.length === 0;
+	}
+	/**
+	* Open the connection with the live config. A failure tears the partial
+	* service down and records the reason for the panel before rethrowing it to
+	* the caller; the plugin fiber is never failed by a connection problem.
+	*/
+	async openConnection() {
+		try {
 			await this.start();
 			this.lastStartError = void 0;
 			this.runningConfig = { ...this.config };
 		} catch (error) {
 			this.lastStartError = messageOf$3(error);
+			this.ctx.logger?.error?.("dsh-channels: 飞书连接失败：%s", String(error));
+			console.error("[dsh-channels] feishu connection failed:", error);
 			try {
 				await this.shutdown();
 			} catch {}
 			throw error;
 		}
 	}
+	/**
+	* Panel action: open the long connection when the channel is stopped.
+	* Credentials are re-checked first — an incomplete pair throws a message the
+	* panel shows next to the credentials form instead of attempting a connect.
+	*/
+	async connect() {
+		if (this.started) return;
+		if (this.connecting || this.restarting) throw new Error("飞书连接正在连接或重启，请稍候再试");
+		this.connecting = true;
+		try {
+			await this.loadOverlay();
+			await this.refreshReadiness();
+			if (!this.configured) throw new Error(`飞书应用凭据尚未配置完整：缺少 ${this.missingConfigItems.join("、")}`);
+			await this.openConnection();
+		} finally {
+			this.connecting = false;
+		}
+	}
 	/** Re-read the Web overlay over the profile config (no channel touch). */
 	async loadOverlay() {
 		const overlay = this.overlay === void 0 ? {} : await this.overlay.load();
@@ -6613,22 +7091,24 @@ var FeishuService = class {
 		});
 		this.refreshRetentionTimer();
 	}
-	/** Tear the connection down and bring it back with the latest config. */
+	/**
+	* Tear the connection down and bring it back with the latest config. When the
+	* credentials are no longer complete the channel simply stays stopped (no
+	* error): the panel then shows the configuration guide instead of a failure.
+	*/
 	async restart() {
-		if (this.restarting) throw new Error("飞书连接正在重启，请稍候再试");
+		if (this.restarting || this.connecting) throw new Error("飞书连接正在连接或重启，请稍候再试");
 		this.restarting = true;
 		try {
 			await this.shutdown();
 			await this.loadOverlay();
-			await this.start();
-			this.lastStartError = void 0;
-			this.runningConfig = { ...this.config };
-		} catch (error) {
-			this.lastStartError = messageOf$3(error);
-			try {
-				await this.shutdown();
-			} catch {}
-			throw error;
+			await this.refreshReadiness();
+			if (!this.configured) {
+				this.lastStartError = void 0;
+				this.runningConfig = void 0;
+				return;
+			}
+			await this.openConnection();
 		} finally {
 			this.restarting = false;
 		}
@@ -6639,6 +7119,18 @@ var FeishuService = class {
 	isRestarting() {
 		return this.restarting;
 	}
+	/** True while the panel's explicit connect action is in flight. */
+	isConnecting() {
+		return this.connecting;
+	}
+	/** Whether both Feishu application credentials currently resolve. */
+	isConfigured() {
+		return this.configured;
+	}
+	/** Names of the missing configuration items (never values). */
+	missingConfig() {
+		return this.missingConfigItems;
+	}
 	startedAtMs() {
 		return this.startedAt;
 	}
@@ -6662,6 +7154,7 @@ var FeishuService = class {
 		const admin = this.config.adminOpenId;
 		return {
 			mode: this.config.accessMode,
+			loaded: this.domain !== void 0,
 			admin: {
 				...admin === void 0 ? {} : { openId: admin },
 				configured: admin !== void 0
@@ -6706,7 +7199,7 @@ var FeishuService = class {
 		const admin = this.config.adminOpenId;
 		if (admin === void 0) return {
 			ok: false,
-			error: "请先在常用配置中设置管理员 open_id"
+			error: "请先在「访问授权」标签页设置管理员 open_id"
 		};
 		try {
 			if (!this.accessStore.hasGroup(id)) await this.accessStore.addGroup({
@@ -6757,7 +7250,7 @@ var FeishuService = class {
 		const admin = this.config.adminOpenId;
 		if (admin === void 0) return {
 			ok: false,
-			error: "请先在常用配置中设置管理员 open_id"
+			error: "请先在「访问授权」标签页设置管理员 open_id"
 		};
 		try {
 			if (!this.accessStore.hasUser(id)) await this.accessStore.addUser({
@@ -6808,7 +7301,7 @@ var FeishuService = class {
 		const actor = this.config.adminOpenId;
 		if (actor === void 0) return {
 			ok: false,
-			error: "请先配置管理员 open_id"
+			error: "请先在「访问授权」标签页配置管理员 open_id"
 		};
 		try {
 			const result = await requests.resolve(token, decision, actor);
@@ -6841,9 +7334,9 @@ var FeishuService = class {
 		return value;
 	}
 	/**
-	* Workspace-retention preview for the Web panel: how many plugin-created
-	* workspaces exist, how many are past the configured window, and their
-	* measured footprint. Never deletes anything.
+	* Retention preview for the Web panel: how many plugin workspaces exist,
+	* how many directories are past the configured window, and their measured
+	* footprint. Never deletes anything.
 	*/
 	async cleanupPreview() {
 		const retention = this.config.workspaceRetention;
@@ -6853,6 +7346,13 @@ var FeishuService = class {
 			...window === void 0 ? {} : { thresholdMs: window },
 			auto: this.config.workspaceRetentionAuto
 		};
+		if (this.domain === void 0) return {
+			...base,
+			workspaces: 0,
+			candidates: 0,
+			candidateBytes: 0,
+			error: "飞书连接建立后即可预览和清理工作区"
+		};
 		try {
 			const workspaces = this.ctx.workspaceRegistry.list().filter((workspace) => this.isPluginWorkspace(workspace));
 			const plan = await planWorkspaceCleanup(this.cleanupDeps());
@@ -6873,26 +7373,36 @@ var FeishuService = class {
 		}
 	}
 	/**
-	* Delete every stale plugin workspace the configured retention allows.
-	* Routes bound to a removed workspace are retired first (thread routes leave
-	* a tombstone), so an old topic fails with the explicit expired card instead
-	* of resuming into a missing directory. DSH Session logs are not touched.
+	* Delete every stale plugin directory the configured retention allows: the
+	* per-topic working directories of current conversations and the legacy
+	* one-workspace-per-topic directories of older versions. User workspaces are
+	* never deleted.
+	*
+	* Active routes bound to a removed directory are retired first (thread
+	* routes leave a tombstone), so an old topic fails with the explicit expired
+	* card instead of resuming into a missing directory. DSH Session logs are not
+	* touched.
 	*/
 	async runWorkspaceCleanup() {
 		const empty = {
 			ok: false,
 			deletedWorkspaces: 0,
+			deletedSessionDirs: 0,
 			retiredRoutes: 0,
 			freedBytes: 0,
 			failures: []
 		};
+		if (this.domain === void 0) return {
+			...empty,
+			error: "飞书连接建立后才能清理工作区"
+		};
 		if (retentionMs(this.config.workspaceRetention) === void 0) return {
 			...empty,
-			error: "未启用工作区清理阈值（workspaceRetention 为 off）"
+			error: "未启用目录清理阈值（workspaceRetention 为 off）"
 		};
 		if (this.cleanupRunning) return {
 			...empty,
-			error: "工作区清理正在进行中，请稍候"
+			error: "目录清理正在进行中，请稍候"
 		};
 		this.cleanupRunning = true;
 		try {
@@ -6900,13 +7410,14 @@ var FeishuService = class {
 			const plan = await planWorkspaceCleanup(deps);
 			if (plan === void 0) return {
 				...empty,
-				error: "工作区清理不可用：baseDir 配置无效"
+				error: "目录清理不可用：baseDir 配置无效"
 			};
 			const outcome = await applyWorkspaceCleanup(deps, plan);
-			this.ctx.logger?.info?.("dsh-channels: workspace cleanup removed %d workspace(s), retired %d route(s), freed %d bytes", outcome.deletedWorkspaces, outcome.retiredRoutes, outcome.freedBytes);
+			this.ctx.logger?.info?.("dsh-channels: retention cleanup removed %d legacy workspace(s) and %d topic dir(s), retired %d route(s), freed %d bytes", outcome.deletedWorkspaces, outcome.deletedSessionDirs, outcome.retiredRoutes, outcome.freedBytes);
 			return {
 				ok: true,
 				deletedWorkspaces: outcome.deletedWorkspaces,
+				deletedSessionDirs: outcome.deletedSessionDirs,
 				retiredRoutes: outcome.retiredRoutes,
 				freedBytes: outcome.freedBytes,
 				failures: outcome.failures.map((failure) => `${failure.path}: ${failure.message}`)
@@ -6931,40 +7442,35 @@ var FeishuService = class {
 			baseDir,
 			retention: this.config.workspaceRetention,
 			listWorkspaces: () => this.ctx.workspaceRegistry.list(),
+			listSessionDirs: () => this.listCleanableSessionDirs(baseDir),
 			activeRoutes: () => [...this.domain?.routes.entries() ?? []].map(([key, record]) => ({
 				key,
 				kind: record.kind,
 				workspacePath: record.workspacePath,
+				...record.sessionDir === void 0 ? {} : { sessionDir: record.sessionDir },
 				sessionId: record.sessionId,
 				lastActivityAt: record.lastActivityAt
 			})),
 			tombstones: () => [...this.domain?.expiredRoutes.entries() ?? []].map(([key, record]) => ({
 				key,
 				...record.workspacePath === void 0 ? {} : { workspacePath: record.workspacePath },
+				...record.sessionDir === void 0 ? {} : { sessionDir: record.sessionDir },
 				expiredAt: record.expiredAt,
 				...record.lastActivityAt === void 0 ? {} : { lastActivityAt: record.lastActivityAt }
 			})),
 			isLive: (sessionId) => this.sessions.get(sessionId) !== void 0 || this.ctx.agents.get(sessionId) !== void 0,
-			statWorkspace: (workspacePath) => measureWorkspace(workspacePath),
+			statWorkspace: (directory) => measureWorkspace(directory),
 			removeWorkspace: async (workspace) => {
-				const target = path.resolve(workspace.path);
-				if (!isPathInside(baseDir, target)) throw new Error(`refusing to delete a path outside baseDir (${target})`);
-				try {
-					const [physicalBase, physicalTarget] = await Promise.all([realpath(baseDir), realpath(target)]);
-					if (!isPathInside(physicalBase, physicalTarget)) throw new Error(`refusing to delete a symlink escape outside baseDir (${physicalTarget})`);
-				} catch (error) {
-					if (error instanceof Error && error.message.startsWith("refusing to delete a symlink escape")) throw error;
-				}
-				await rm(target, {
-					recursive: true,
-					force: true
-				});
+				await this.deleteDirectoryInsideBase(baseDir, workspace.path);
 				try {
 					await this.ctx.workspaceRegistry.delete(workspace.id);
 				} catch (error) {
 					this.ctx.logger?.warn?.("dsh-channels: unregistering cleaned workspace %s failed: %s", workspace.path, String(error));
 				}
 			},
+			removeSessionDir: async (directory) => {
+				await this.deleteDirectoryInsideBase(baseDir, directory);
+			},
 			retireRoute: async (route) => {
 				if (route.kind === "thread") await this.routes.retire(route.key);
 				else await this.routes.remove(route.key);
@@ -6973,6 +7479,65 @@ var FeishuService = class {
 		};
 	}
 	/**
+	* Scan the live user workspaces for per-topic working directories that no
+	* route record points at anymore (for example the old route of a degraded
+	* chat conversation was deleted by TTL retirement). Route/tombstone evidence
+	* wins for age; the scan mtime only covers true orphans.
+	*/
+	async listCleanableSessionDirs(baseDir) {
+		const legacyRoot = legacyTopicWorkspaceRoot(baseDir);
+		const roots = [];
+		for (const workspace of this.ctx.workspaceRegistry.list()) {
+			if (!this.isPluginWorkspace(workspace)) continue;
+			const resolved = path.resolve(workspace.path);
+			if (isPathInside(legacyRoot, resolved)) continue;
+			roots.push(resolved);
+		}
+		const scanned = [];
+		for (const root of roots) for (const relative of ["topics", path.join(".agents", "worktrees")]) {
+			const directory = path.join(root, relative);
+			let entries;
+			try {
+				entries = await readdir(directory, { withFileTypes: true });
+			} catch {
+				continue;
+			}
+			for (const entry of entries) {
+				if (!entry.isDirectory()) continue;
+				const candidate = path.join(directory, entry.name);
+				try {
+					const info = await lstat(candidate);
+					if (info.isDirectory()) scanned.push({
+						path: candidate,
+						mtimeMs: info.mtimeMs
+					});
+				} catch {}
+			}
+		}
+		return scanned;
+	}
+	/**
+	* Recursively delete one plugin directory below `baseDir`.
+	*
+	* The lexical check refuses paths outside `baseDir`; the realpath check then
+	* refuses a symlinked ancestor that would let the recursive delete escape
+	* the plugin root. A missing directory is already effectively removed.
+	*/
+	async deleteDirectoryInsideBase(baseDir, target) {
+		const resolved = path.resolve(target);
+		if (!isPathInside(baseDir, resolved)) throw new Error(`refusing to delete a path outside baseDir (${resolved})`);
+		try {
+			const [physicalBase, physicalTarget] = await Promise.all([realpath(baseDir), realpath(resolved)]);
+			if (!isPathInside(physicalBase, physicalTarget)) throw new Error(`refusing to delete a symlink escape outside baseDir (${physicalTarget})`);
+		} catch (error) {
+			if (error instanceof Error && error.message.startsWith("refusing to delete a symlink escape")) throw error;
+		}
+		await rm(resolved, {
+			recursive: true,
+			force: true
+		});
+	}
+	/**
 	* (Re)arm the daily retention timer to match the live config. `runNow`
 	* performs one pass immediately; it is only used at startup so saving any
 	* unrelated setting can never trigger a surprise deletion pass.
@@ -6985,7 +7550,7 @@ var FeishuService = class {
 		if (!this.started || !this.config.workspaceRetentionAuto || retentionMs(this.config.workspaceRetention) === void 0) return;
 		const sweep = () => {
 			this.runWorkspaceCleanup().then((result) => {
-				if (!result.ok && result.error !== "工作区清理正在进行中，请稍候") this.ctx.logger?.warn?.("dsh-channels: automatic workspace cleanup failed: %s", result.error);
+				if (!result.ok && result.error !== "目录清理正在进行中，请稍候") this.ctx.logger?.warn?.("dsh-channels: automatic workspace cleanup failed: %s", result.error);
 			});
 		};
 		if (runNow) sweep();
@@ -7051,6 +7616,7 @@ var FeishuService = class {
 		} catch (error) {
 			throw new Error(`写入凭据引用 ${ref} 失败：${messageOf$3(error)}`);
 		}
+		await this.refreshReadiness();
 	}
 	/** Remove the stored value of one Feishu credential reference. */
 	async clearCredential(field) {
@@ -7062,6 +7628,7 @@ var FeishuService = class {
 		} catch (error) {
 			throw new Error(`移除凭据引用 ${ref} 失败：${messageOf$3(error)}`);
 		}
+		await this.refreshReadiness();
 	}
 	/** The overlay-independent ref name backing one editable credential slot. */
 	credentialRef(field) {
@@ -7136,12 +7703,12 @@ var FeishuService = class {
 			answerer.onCardAction(event);
 			questions.onCardAction(event);
 		});
-		this.ctx.on("session/event", (session, event) => {
+		this.unlistenHost.push(this.ctx.on("session/event", (session, event) => {
 			this.streamer?.onSessionEvent(session, event);
-		});
-		this.ctx.on("agent/assistant-stream", ({ agent, frame }) => {
+		}));
+		this.unlistenHost.push(this.ctx.on("agent/assistant-stream", ({ agent, frame }) => {
 			this.streamer?.onAssistantFrame(agent.session, frame);
-		});
+		}));
 		this.unlisten = channel.onMessage((message) => {
 			this.inbound.handle(message).catch((error) => {
 				this.ctx.logger?.warn?.("dsh-channels inbound error: %s", String(error));
@@ -7198,6 +7765,7 @@ var FeishuService = class {
 		this.unlistenApproval = void 0;
 		this.unlistenQuestions?.();
 		this.unlistenQuestions = void 0;
+		for (const dispose of this.unlistenHost.splice(0)) dispose();
 		this.approvalAnswerer?.dispose();
 		this.approvalAnswerer = void 0;
 		this.questionAnswerer?.dispose();
@@ -7699,7 +8267,7 @@ var FeishuService = class {
 			await this.delivery.standaloneReply(msg, buildRenewCard({
 				previousSessionId: renewAdmission.commit.previous.sessionId,
 				currentSessionId: renewAdmission.commit.current.sessionId,
-				workspacePath: renewAdmission.commit.current.workspacePath
+				sessionDir: sessionDirOf(renewAdmission.commit.current)
 			}));
 			return;
 		}
@@ -7717,7 +8285,7 @@ var FeishuService = class {
 				context,
 				extras: {
 					permissionPreset: this.permissionPresetOf(session),
-					workspacePath: current.workspacePath,
+					sessionDir: sessionDirOf(current),
 					uptimeMs: this.startedAt === void 0 ? void 0 : Date.now() - this.startedAt,
 					liveAgents: this.sessions.liveCount(),
 					routeCount: this.routes.size()
@@ -7726,7 +8294,10 @@ var FeishuService = class {
 			return;
 		}
 		if (spec.name === "workspace" && result.kind === "success") {
-			const resolved = resolveWorkDir(live.agent.session.header.cwd, current.workspacePath);
+			const resolved = resolveWorkDir(live.agent.session.header.cwd, {
+				workspacePath: current.workspacePath,
+				...current.sessionDir === void 0 ? {} : { sessionDir: current.sessionDir }
+			});
 			if (resolved.kind === "success") {
 				await this.delivery.standaloneReply(msg, buildWorkDirCard(current.sessionId, resolved.path));
 				return;
@@ -8168,6 +8739,9 @@ const FEISHU_LOGGER_LEVELS = [
 ];
 /** Same shape as the host credentials seam's `CredentialRef` (shell identifier). */
 const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Conventional credential-reference names used when the loader passes no config. */
+const DEFAULT_APP_ID_REF = "FEISHU_APP_ID";
+const DEFAULT_APP_SECRET_REF = "FEISHU_APP_SECRET";
 /** Default route-table GC threshold: 30 days without activity. */
 const DEFAULT_ROUTE_TTL_MS = 720 * 60 * 60 * 1e3;
 /** Default HITL approval decision window: 5 minutes per question. */
@@ -8177,10 +8751,10 @@ const DEFAULT_QUESTION_TIMEOUT_MS = 300 * 1e3;
 /** A credential reference: `FEISHU_APP_ID`-style name resolved through ctx.credentials. */
 const credentialRefSchema = z.string().regex(CREDENTIAL_REF_PATTERN, "must be a credential reference name such as FEISHU_APP_ID (resolved through the dsh credentials seam, e.g. $DSH_HOME/.credentials.yaml) — plaintext secrets are not accepted");
 const configSchema = z.object({
-	/** Feishu app id credential reference (e.g. `FEISHU_APP_ID`). */
-	appId: credentialRefSchema,
-	/** Feishu app secret credential reference (e.g. `FEISHU_APP_SECRET`). */
-	appSecret: credentialRefSchema,
+	/** Feishu app id credential reference (defaults to `FEISHU_APP_ID`). */
+	appId: credentialRefSchema.default(DEFAULT_APP_ID_REF),
+	/** Feishu app secret credential reference (defaults to `FEISHU_APP_SECRET`). */
+	appSecret: credentialRefSchema.default(DEFAULT_APP_SECRET_REF),
 	/**
 	* Root directory for per-(user, chat) workspace directories — the filesystem
 	* root where files produced by channel sessions land. Read per session
@@ -8240,6 +8814,27 @@ const configSchema = z.object({
 	*/
 	threadFallback: z.enum(["degrade", "strict"]).default("degrade"),
 	/**
+	* Per-topic working-directory isolation inside one user workspace.
+	*
+	* - `auto` (default): use a Git worktree per topic when the user workspace
+	*   is a Git repository (the workspace directory contains `.git`), otherwise
+	*   a plain subdirectory.
+	* - `subdir`: always a plain subdirectory (no Git requirement, no duplicated
+	*   checkouts).
+	* - `worktree`: always try a Git worktree; when the workspace is not a Git
+	*   repository, the `worktrees` service is unavailable, or creation is
+	*   denied, log a warning and fall back to a subdirectory.
+	*
+	* The workspace itself stays the Session header cwd either way, so Sessions
+	* remain grouped under the user's project; only the effective working
+	* directory changes. See `docs/workspace-isolation-design.md`.
+	*/
+	topicIsolation: z.enum([
+		"auto",
+		"subdir",
+		"worktree"
+	]).default("auto"),
+	/**
 	* Route-table GC threshold. Route records (and stale in-flight repair
 	* snapshots) whose last activity is older than this many milliseconds are
 	* retired at startup and on every periodic sweep. Real thread routes leave a
@@ -8265,17 +8860,19 @@ const configSchema = z.object({
 	*/
 	acceptAttachments: z.boolean().default(true),
 	/**
-	* Delete the workspace directories of stale conversations. `off` (default)
-	* never deletes; `7d`/`30d`/`90d`/`180d` remove plugin-created workspaces
-	* whose last activity is older than the threshold. The managed Web panel
-	* exposes this as a select, previews the candidates, and can run one
-	* cleanup manually. DSH Session logs are never deleted.
+	* Delete the topic directories of stale conversations, plus legacy
+	* one-workspace-per-topic directories written by older plugin versions.
+	* `off` (default) never deletes; `7d`/`30d`/`90d`/`180d` remove those
+	* directories when their last activity is older than the threshold. User
+	* workspaces themselves are never deleted. The managed Web panel exposes
+	* this as a select, previews the candidates, and can run one cleanup
+	* manually. DSH Session logs are never deleted.
 	*/
 	workspaceRetention: z.enum(WORKSPACE_RETENTION_VALUES).default("off"),
 	/**
-	* Run the workspace-retention cleanup at startup and once per day. Off by
-	* default: deletion is irreversible, so it stays an explicit opt-in even
-	* when a retention threshold is configured.
+	* Run the retention cleanup at startup and once per day. Off by default:
+	* deletion is irreversible, so it stays an explicit opt-in even when a
+	* retention threshold is configured.
 	*/
 	workspaceRetentionAuto: z.boolean().default(false),
 	/**
@@ -8323,6 +8920,14 @@ const configSchema = z.object({
 	questionTimeoutMs: z.number().int().min(1e4).max(36e5).default(DEFAULT_QUESTION_TIMEOUT_MS)
 });
 /**
+* DSH loader-facing schema. The bundle patch inserts this plugin without a
+* `config` object; the loader validates that row with `undefined` before the
+* user's patch layer supplies values. Accept that absence and fill the same
+* defaults as {@link resolveConfig}, so enabling the plugin from the Web UI
+* cannot fail with "expected object, received undefined".
+*/
+const pluginConfigSchema = configSchema.prefault({});
+/**
 * Validate the raw loader config. Values stay credential *references*; the
 * secrets themselves resolve through `ctx.credentials` at startup.
 * @param raw - the config object the cordis loader passed (may be undefined).
@@ -8351,10 +8956,15 @@ const STATUS_ROUTE = "/dsh-channels/status";
 const PANEL_ROUTE = "/dsh-channels/panel";
 const CONFIG_ROUTE = "/dsh-channels/config";
 const CREDENTIALS_ROUTE = "/dsh-channels/credentials";
+/**
+* Connection lifecycle action (POST). While the channel runs it restarts the
+* long connection; while it is stopped it opens one — so the panel has exactly
+* one "connect / reconnect" button. Credentials are resolved again either way.
+*/
 const RECONNECT_ROUTE = "/dsh-channels/reconnect";
 /** 模型/推理档位/预设选择器的宿主目录（provider → model → effort 级联刷新）。 */
 const CATALOG_ROUTE = "/dsh-channels/catalog";
-/** 手动执行一次过期工作区清理（POST，无请求体）。 */
+/** 手动执行一次过期目录清理（POST，无请求体）。 */
 const CLEANUP_ROUTE = "/dsh-channels/cleanup";
 /** 访问与授权只读快照（GET/HEAD）：准入模式、管理员、群/用户白名单、待处理申请。 */
 const ACCESS_ROUTE = "/dsh-channels/access";
@@ -8365,6 +8975,14 @@ const ACCESS_USERS_ROUTE = "/dsh-channels/access/users";
 /** 结算一条待处理授权申请（POST，body `{ token, decision }`）。 */
 const ACCESS_REQUESTS_ROUTE = "/dsh-channels/access/requests";
 /**
+* 打开宿主机的系统目录选择框（POST，无请求体），返回绝对路径。
+*
+* 只有宿主挂载了 `directoryPicker` 的 native 后端（桌面/本地 GUI 会话）才
+* 会注册实际选择逻辑；远程/无头会话的 browse 后端不可用，面板不下发
+* [`EditableFieldWire.browse`]，保留手写输入。
+*/
+const PICK_DIRECTORY_ROUTE = "/dsh-channels/pick-directory";
+/**
 * 可由 Web 面板覆盖的配置项。全部是 `src/config.ts` 里已存在的字段；
 * 覆盖值写进 `$DSH_HOME/dsh-channels/settings.json`，优先级高于 profile
 * 的 `cordis.patch.yml`（见 README「Web 设置面板」）。
@@ -8374,7 +8992,7 @@ const ACCESS_REQUESTS_ROUTE = "/dsh-channels/access/requests";
 * 因此不会落进覆盖层文件。
 *
 * `baseDir`（工作区根目录 = 模型/工具产生文件的落点）可覆盖，但面板只接受
-* **绝对路径**（`~` 会展开）；已有 Session / 工作区不迁移，只影响之后新建的
+* **绝对路径**（`~` 会展开）；已有 Session / 目录不迁移，只影响之后新建的
 * 会话。校验与保存时建目录见 `src/workspaces.ts`。
 */
 const EDITABLE_KEYS = [
@@ -8412,22 +9030,55 @@ const RESTART_KEYS = [
 /** Display labels for the panel header/cards (kept on the wire so the client owns no copy). */
 const PANEL_COPY = {
 	title: "飞书渠道",
-	description: "飞书长连接状态、应用凭据与常用配置。凭据写入 DSH 凭据库且不回显；标注「需重连」的项需重启飞书连接生效。",
+	description: "飞书长连接、应用凭据与渠道配置。凭据只写入 DSH 凭据库且不回显；标注「需重连」的项在连接建立时读取。",
 	statusCard: "连接状态",
+	phaseUnconfigured: "待配置",
+	phaseIdle: "未连接",
+	phaseConnecting: "连接中",
+	phaseConnected: "已连接",
+	phaseError: "连接失败",
+	configuredBadge: "凭据已配置",
+	unconfiguredBadge: "凭据未配置",
+	statusSummaryConnected: "飞书长连接已建立，机器人可以收发消息。",
+	statusSummaryUnconfigured: "尚未配置飞书应用凭据：插件已加载，但不会连接飞书。填写凭据并保存后会自动连接。",
+	statusSummaryIdle: "飞书应用凭据已就绪，但当前没有建立长连接。",
+	statusSummaryConnecting: "正在连接飞书长连接…",
+	statusSummaryError: "最近一次连接飞书失败，请检查凭据与网络后重试。",
+	lastError: "最近一次连接失败",
+	missingConfig: "缺少配置",
+	statusHintUnconfigured: "配置完成后插件会自动连接；也可以稍后在本页手动连接。",
+	connectionInfo: "连接信息",
+	connectionStateLabel: "飞书长连接",
+	botOpenId: "Bot open_id",
+	uptime: "运行时长",
+	routeCount: "话题路由",
+	liveAgentCount: "活动会话",
+	inflightTurnCount: "在途回复",
+	healthReasons: "健康判定",
+	unknownValue: "—",
+	connect: "连接飞书",
+	connecting: "连接中…",
+	onboardingTitle: "开始使用飞书渠道",
+	onboardingIntro: "只需三步：在飞书开放平台创建自建应用，把 App ID / App Secret 填入本页，保存后自动连接。",
+	onboardingStep1Title: "创建飞书自建应用",
+	onboardingStep1Text: "在飞书开放平台创建企业自建应用，开启机器人能力；事件订阅选择「长连接」，订阅 im.message.receive_v1（接收消息）。",
+	onboardingStep2Title: "填写应用凭据",
+	onboardingStep2Text: "把应用的 App ID（cli_ 开头）与 App Secret 填入下方「飞书应用凭据」，值会写入 DSH 凭据库。",
+	onboardingStep3Title: "保存并等待连接",
+	onboardingStep3Text: "两项凭据都保存后插件会自动连接；状态变为「已连接」即可在飞书里私聊机器人。",
+	onboardingDocsHint: "开放平台地址：open.feishu.cn/app；应用需要开通 im:message、im:message:send_as_bot 等消息权限。",
 	credentialsCard: "飞书应用凭据",
-	modelCard: "模型与推理",
-	modelCardHelp: "模型服务商、模型 id、推理档位与新会话的 Agent 预设。下拉选项来自宿主机实时目录；保存后对新会话生效。",
-	configCard: "常用配置",
-	advancedCard: "只读与高级信息",
+	credentialsCardHelp: "凭据值经 DSH 凭据服务写入本机凭据库；面板只显示「已配置 / 未配置」，永不回显已存值。两项都配置后才会连接飞书。",
 	appIdLabel: "飞书 App ID",
 	appSecretLabel: "飞书 App Secret",
-	credentialsHelp: "值通过 DSH 凭据服务写入本机凭据库；面板只显示是否已配置，永不回显已存值。留空表示保持当前值。",
 	credentialsRef: "凭据引用",
 	saveCredentials: "保存凭据",
 	savingCredentials: "保存中…",
 	credentialSaved: "凭据已保存",
-	credentialSavedReconnected: "凭据已保存，已自动重连飞书通道",
+	credentialSavedReconnected: "凭据已保存，飞书已连接",
 	credentialSavedPending: "凭据已保存，重启飞书连接后生效",
+	credentialSavedUnconfigured: "凭据已保存；还缺少另一项凭据，补齐后会自动连接",
+	credentialAutoConnectFailed: "凭据已保存，但自动连接失败",
 	credentialRemoved: "已移除存储的凭据",
 	credentialRemovedPending: "已移除存储的凭据，重启飞书连接后生效",
 	removeCredential: "移除已存值",
@@ -8437,40 +9088,62 @@ const PANEL_COPY = {
 	credentialReadOnly: "当前凭据存储不可写",
 	appIdPlaceholder: "输入 App ID（cli_…）",
 	appSecretPlaceholder: "输入 App Secret",
-	save: "保存配置",
-	saveAll: "保存全部配置",
-	saveModel: "保存模型配置",
-	modelActionsHint: "只保存模型与推理字段",
+	credentialsPendingHint: "填写后点「保存凭据」；两项齐全时插件会自动连接飞书。",
+	connectionTabHelp: "连接状态与飞书应用凭据。凭据不完整时不会连接飞书。",
+	sessionsTabHelp: "私聊、群聊触发方式与入站内容；「需重连」项在下次连接时读取。",
+	modelTabHelp: "飞书会话使用的模型服务商、模型、推理档位与 Agent 预设；下拉选项来自宿主机实时目录，保存后对新会话生效。",
+	workspaceTabHelp: "每个用户一个工作区（模型/工具产生文件的落点），每个话题在其中拥有独立工作目录；只影响之后新建的话题。",
+	accessTabHelp: "准入采用 fail-closed：管理员不受白名单限制，非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。",
+	advancedTabHelp: "流式刷新等低层参数、Web 覆盖文件与只读信息。",
+	save: "保存更改",
 	saving: "保存中…",
+	saveHintDirty: "只保存改动过的字段；标注「需重连」的项在下次连接时生效。",
+	discardTab: "放弃本页更改",
+	saveHintClean: "没有未保存的更改。",
+	dirtyCount: "未保存项",
+	browseDirectory: "选择目录…",
+	browsingDirectory: "选择中…",
+	directoryPicked: "已选择目录",
+	directoryPickFailed: "无法打开系统目录选择器",
+	saved: "已保存",
+	cleared: "已清除 Web 覆盖，恢复为 profile 配置",
 	clear: "清除 Web 覆盖",
 	clearing: "清除中…",
+	noOverrides: "当前没有 Web 覆盖",
+	overridden: "Web 覆盖",
+	inherited: "继承 profile",
+	restartTag: "需重连",
+	restartBanner: "以下配置需重启飞书连接后生效：",
+	restartWarning: "重启会断开当前飞书长连接并中断进行中的回复，请确认空闲时操作。",
 	reconnect: "重启飞书连接",
 	reconnecting: "重连中…",
 	refresh: "刷新状态",
 	retry: "重试",
+	pollFailed: "状态刷新失败",
+	connectDone: "已连接飞书",
+	reconnectDone: "已重启飞书连接",
+	saveInvalid: "请先修正标红的配置项",
+	enabled: "已启用",
+	disabled: "已关闭",
+	credentialRemoveConfirm: "确定移除已存储的凭据值？移除后不会回显，需要时须重新填写。",
+	accessNotLoaded: "飞书连接建立后加载授权列表",
 	loading: "加载中…",
 	loadFailed: "设置面板加载失败",
-	saved: "已保存",
-	savedModel: "模型配置已保存",
-	cleared: "已清除 Web 覆盖，恢复为 profile 配置",
 	catalogFailed: "模型目录加载失败，已退回手填。",
 	catalogLoading: "正在读取宿主机选项…",
 	catalogUnavailable: "宿主机未提供可选项，请手填。",
-	noOverrides: "当前没有 Web 覆盖",
-	overridden: "Web 覆盖",
-	inherited: "继承 profile",
-	restartTag: "需重连",
-	restartBanner: "以下配置需重启飞书连接后生效：",
-	restartWarning: "重启会断开当前飞书长连接并中断进行中的回复，请确认空闲时操作。",
-	lastError: "最近一次启动失败",
-	notRunning: "未运行",
 	version: "插件版本",
 	overlayPath: "覆盖文件",
-	cleanupCard: "工作区清理",
-	cleanupCardHelp: "删除超过保留期且不再活跃的飞书工作区目录；只会删除本插件在「工作区根目录」下创建的目录，DSH 会话日志不删除。删除不可恢复：相关旧话题会失效并提示已过期，工作区列表记录同步移除。",
+	overlayPathHelp: "可以直接编辑该 JSON 文件；面板保存会整体重写它，「清除 Web 覆盖」会删除它并回落到 profile 配置。",
+	advancedCard: "只读与高级信息",
+	advancedHelp: "这些值来自 profile 配置，不能在面板里编辑。",
+	readOnlyCard: "部署级参数",
+	cleanupCard: "目录清理",
+	cleanupCardHelp: "删除超过保留期且不再活跃的飞书话题目录（以及旧版本按话题建立的工作区目录）；用户工作区本身、DSH 会话日志都不会删除。删除不可恢复：相关旧话题会失效并提示已过期。",
 	cleanupRetention: "保留期",
 	cleanupAutoLabel: "自动清理",
-	cleanupCandidates: "可清理工作区",
+	cleanupCandidates: "可清理目录",
+	cleanupWorkspaces: "插件工作区",
 	cleanupCandidateBytes: "预计释放空间",
 	cleanupRetentionOff: "关闭（不删除）",
 	cleanupAutoOn: "已开启（启动时 + 每天一次）",
@@ -8478,24 +9151,22 @@ const PANEL_COPY = {
 	cleanupAutoInactive: "未执行（保留期为关闭）",
 	cleanupNow: "立即清理",
 	cleanupRunning: "清理中…",
-	cleanupConfirm: "确定清理过期工作区吗？该操作不可恢复，会删除这些工作区内的全部文件（包括 attachments/ 附件）。",
-	cleanupConfirmHint: "删除前会再次确认；保留期为「关闭」或没有过期工作区时按钮不可用。",
-	cleanupDisabledOff: "保留策略为「关闭」：请先在「常用配置 → 工作区与文件」中选择保留天数。",
-	cleanupDisabledEmpty: "没有超过保留期的过期工作区。",
+	cleanupConfirm: "确定清理过期目录吗？该操作不可恢复，会删除这些目录内的全部文件（包括 attachments/ 附件）。",
+	cleanupConfirmHint: "删除前会再次确认；保留期为「关闭」或没有过期目录时按钮不可用。",
+	cleanupDisabledOff: "保留策略为「关闭」：请先在上方「过期目录保留期」中选择保留天数。",
+	cleanupDisabledEmpty: "没有超过保留期的过期目录。",
 	cleanupPreviewFailed: "无法读取清理预览",
 	cleanupDone: "清理完成",
 	cleanupFailed: "清理失败",
 	cleanupDeleted: "已删除工作区",
+	cleanupDeletedDirs: "话题目录",
 	cleanupRetired: "已清理话题路由",
 	cleanupFreed: "释放空间",
-	cleanupFailures: "以下工作区未能删除：",
+	cleanupFailures: "以下目录未能删除：",
 	accessCard: "访问与授权",
-	accessCardHelp: "准入采用 fail-closed：管理员不受白名单限制（私聊、任意群聊都可直接对话）；非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。管理员 open_id 在「常用配置 → 行为」中填写，私聊机器人发送 /userid 获取。",
+	accessCardHelp: "准入采用 fail-closed：管理员不受白名单限制（私聊、任意群聊都可直接对话）；非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。管理员与准入模式在上方「准入与授权」中编辑；私聊机器人发送 /userid 获取自己的 open_id。",
 	accessModeOpenWarning: "当前准入模式为开放（open）：应用可用范围内的任何人都能开启对话。该模式不安全，仅建议调试时使用。",
-	accessAdminMissingWarning: "当前准入=guarded 但未配置管理员，所有对话都会被拒绝。请先在「常用配置 → 行为 → 管理员 open_id」填写。",
-	accessAdminLabel: "管理员",
-	accessAdminMissing: "未配置",
-	accessAdminHint: "修改管理员请到「常用配置 → 行为 → 管理员 open_id」；私聊机器人发送 /userid 可查看自己的 open_id（ou_ 开头，不是 user_id/邮箱）。",
+	accessAdminMissingWarning: "当前准入=guarded 但未配置管理员，所有对话都会被拒绝。请在上方「准入与授权」填写管理员 open_id。",
 	accessGroupsTitle: "已授权群",
 	accessGroupsEmpty: "尚未授权任何群。机器人被拉进群后，管理员会收到带 chat_id 的群信息卡；也可在群内发送 /groupid 获取。",
 	accessUsersTitle: "已授权用户",
@@ -8951,7 +9622,7 @@ function registerSettingsRoutes(server, surface) {
 					return;
 				}
 				const result = await surface.reconnect();
-				sendJson(res, result.ok ? 200 : 500, result);
+				sendJson(res, result.ok ? 200 : result.unconfigured === true ? 400 : 500, result);
 			})
 		}),
 		server.register({
@@ -8967,6 +9638,41 @@ function registerSettingsRoutes(server, surface) {
 				sendJson(res, result.ok ? 200 : 500, result);
 			})
 		}),
+		server.register({
+			kind: "exact",
+			path: PICK_DIRECTORY_ROUTE,
+			handler: guarded(async (req, res) => {
+				if (!allowOnly(req, res, ["POST"])) return;
+				if (!isSameOriginRequest(req)) {
+					forbiddenWrite(res);
+					return;
+				}
+				const controller = new AbortController();
+				let answered = false;
+				if (typeof res.on === "function") res.on("close", () => {
+					if (!answered) controller.abort();
+				});
+				let path;
+				try {
+					path = await surface.pickDirectory(controller.signal);
+				} catch (error) {
+					answered = true;
+					if (controller.signal.aborted) {
+						res.end();
+						return;
+					}
+					throw error;
+				}
+				answered = true;
+				sendJson(res, 200, path === null ? {
+					ok: true,
+					canceled: true
+				} : {
+					ok: true,
+					path
+				});
+			})
+		}),
 		server.register({
 			kind: "exact",
 			path: ACCESS_ROUTE,
@@ -9145,7 +9851,7 @@ const SELECT_OPTIONS = {
 const FIELD_META = {
 	baseDir: {
 		label: "工作区根目录（文件落点）",
-		help: "每个飞书话题拥有独立工作区：私聊 <baseDir>/topics/p2p/<open_id>/<topic>/，群聊 <baseDir>/topics/groups/<chat_id>/<open_id>/<topic>/（topic 来自话题 id）。必须是绝对路径（~ 开头按家目录展开），保存时会创建该目录；只影响之后新建立的工作区 —— 已有话题即使 /renew 也沿用原工作区，旧文件不会迁移。",
+		help: "每个用户/群成员一个工作区：私聊 <baseDir>/p2p/<open_id>/，群聊 <baseDir>/groups/<chat_id>/<open_id>/；每个话题在其中拥有独立工作目录 <工作区>/topics/<话题>/（Git 仓库工作区可自动改用 worktree）。必须是绝对路径（~ 开头按家目录展开），保存时会创建该目录；只影响之后新建立的会话 —— 已有话题即使 /renew 也沿用原目录，旧文件不会迁移。",
 		placeholder: "/Users/you/.dsh/dsh-channels/workspaces",
 		wide: true
 	},
@@ -9180,7 +9886,7 @@ const FIELD_META = {
 	},
 	authRequestTtlDays: {
 		label: "授权申请有效期（天）",
-		help: "入群/用户授权申请卡的有效期，1–30 天；过期后卡片需重新触发申请（也可直接在「访问与授权」面板处理）。",
+		help: "入群/用户授权申请卡的有效期，1–30 天；过期后卡片需重新触发申请（也可在本页下方「待处理申请」中处理）。",
 		min: 1,
 		max: 30,
 		step: 1
@@ -9190,12 +9896,12 @@ const FIELD_META = {
 		help: "接收飞书图片、文件与合并转发记录，保存到工作区的 attachments/ 目录；模型不会自动读取，需要时用文件工具自行查看。关闭后附件消息不保存、不触发回复。"
 	},
 	workspaceRetention: {
-		label: "过期工作区保留期",
-		help: "超过所选天数没有活动的飞书工作区会进入下方「工作区清理」列表；「关闭」表示永不删除。DSH 会话日志不受影响。"
+		label: "过期目录保留期",
+		help: "超过所选天数没有活动的飞书话题目录（以及旧版本按话题建立的工作区目录）会进入下方清理列表；用户工作区本身永不删除。DSH 会话日志不受影响。"
 	},
 	workspaceRetentionAuto: {
-		label: "自动执行工作区清理",
-		help: "开启后插件在启动时及每天执行一次过期工作区清理；关闭时只能在下方卡片手动清理。开启前请确认保留期已设置。"
+		label: "自动执行目录清理",
+		help: "开启后插件在启动时及每天执行一次过期目录清理；关闭时只能在下方卡片手动清理。开启前请确认保留期已设置。"
 	},
 	provider: {
 		label: "模型服务商",
@@ -9245,9 +9951,9 @@ const GROUP_OF = {
 	threadFallback: "behavior",
 	welcomeOnboarding: "behavior",
 	allowPermissionSwitch: "behavior",
-	adminOpenId: "behavior",
-	accessMode: "behavior",
-	authRequestTtlDays: "behavior",
+	adminOpenId: "access",
+	accessMode: "access",
+	authRequestTtlDays: "access",
 	acceptAttachments: "content",
 	provider: "model",
 	model: "model",
@@ -9343,6 +10049,22 @@ function withCurrentOption(options, value) {
 		...rest
 	];
 }
+/**
+* Mark the workspace-root field as browsable when the host can open its native
+* directory chooser. Every other host (no `directoryPicker`, or the `browse`
+* backend of remote/headless sessions) keeps the plain text input.
+*
+* @param fields - Host field descriptors after the selector catalog is applied.
+* @param available - whether a native directory chooser can be opened.
+* @returns the descriptors with `browse: 'directory'` on `baseDir` when usable.
+*/
+function withDirectoryBrowse(fields, available) {
+	if (!available) return [...fields];
+	return fields.map((field) => field.key === "baseDir" ? {
+		...field,
+		browse: "directory"
+	} : field);
+}
 function messageOf$1(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -9443,6 +10165,12 @@ function normalizeAccessName(raw) {
 /** Build the read-only advanced card from the effective config. */
 function readOnlyFields(config) {
 	return [
+		{
+			key: "topicIsolation",
+			label: "话题目录隔离",
+			value: config.topicIsolation === "auto" ? "自动（Git 仓库用 worktree，否则普通子目录）" : config.topicIsolation === "worktree" ? "Git worktree（失败回退子目录）" : "普通子目录",
+			help: "每个话题的独立工作目录形式；在 profile 配置里用 topicIsolation 设置（auto / subdir / worktree）。"
+		},
 		{
 			key: "routeTtlMs",
 			label: "话题路由过期",
@@ -9467,12 +10195,28 @@ function readOnlyFields(config) {
 		}
 	];
 }
+/**
+* Derive the panel phase from readiness + runtime facts. The order matters:
+* an incomplete configuration always wins (no connection is attempted), and a
+* failed attempt is only reported while the channel is stopped.
+*/
+function phaseOf(target) {
+	if (target.isRestarting()) return "connecting";
+	if (target.isConnecting()) return target.isConfigured() ? "connecting" : "unconfigured";
+	if (target.isRunning()) return "connected";
+	if (!target.isConfigured()) return "unconfigured";
+	if (target.startError() !== void 0) return "error";
+	return "idle";
+}
 /** Assemble the status half of the panel payload. */
 function buildStatus(target, overlayPath) {
 	const health = target.health();
 	const connection = health.connection;
 	return {
 		running: target.isRunning(),
+		configured: target.isConfigured(),
+		phase: phaseOf(target),
+		missingConfig: [...target.missingConfig()],
 		level: health.level,
 		startedAt: target.startedAtMs(),
 		uptimeMs: target.uptimeMs(),
@@ -9490,7 +10234,7 @@ function buildStatus(target, overlayPath) {
 		reasons: health.reasons,
 		version: DSH_CHANNELS_VERSION,
 		overlayPath,
-		busy: target.isRestarting()
+		busy: target.isRestarting() || target.isConnecting()
 	};
 }
 /**
@@ -9505,14 +10249,41 @@ var SettingsSurface = class {
 	store;
 	logger;
 	catalog;
-	constructor(target, store, logger, catalog) {
+	directoryPicker;
+	constructor(target, store, logger, catalog, directoryPicker) {
 		this.target = target;
 		this.store = store;
 		this.logger = logger;
 		this.catalog = catalog;
+		this.directoryPicker = directoryPicker;
+	}
+	/**
+	* Re-read credential presence. The credentials store is hot-reloaded from
+	* disk, so a value edited outside the panel becomes visible within one poll
+	* instead of only after a restart/connect.
+	*/
+	async syncReadiness() {
+		try {
+			await this.target.refreshReadiness();
+		} catch (error) {
+			this.logger?.warn?.("dsh-channels: 凭据状态刷新失败：%s", messageOf$1(error));
+		}
+	}
+	/**
+	* Reject panel writes while the connection lifecycle is in flight: saving an
+	* overlay or credentials then would race `applyOverlay()`/`start()` and can
+	* record a running-config snapshot that never took effect.
+	*/
+	writeBusy() {
+		if (!this.target.isRestarting() && !this.target.isConnecting()) return void 0;
+		return {
+			ok: false,
+			error: "飞书连接正在连接或重启，请稍候再试"
+		};
 	}
 	/** Wire status only (used by the client's 5 s poll). */
 	async status() {
+		await this.syncReadiness();
 		return buildStatus(this.target, this.store.file);
 	}
 	/**
@@ -9531,6 +10302,7 @@ var SettingsSurface = class {
 	}
 	/** Status + editable config with provenance + read-only facts. */
 	async panel() {
+		await this.syncReadiness();
 		const base = this.target.baseConfigSnapshot();
 		const effective = this.target.configSnapshot();
 		const overlay = await this.store.load();
@@ -9538,12 +10310,12 @@ var SettingsSurface = class {
 		const overriddenKeys = EDITABLE_KEYS.filter((key) => overlay[key] !== void 0);
 		const restartPendingKeys = this.target.isRunning() && running !== void 0 ? RESTART_KEYS.filter((key) => effective[key] !== running[key]) : [];
 		const catalog = await this.catalogFor(effective.provider, effective.model);
-		const fields = applyCatalog(FIELD_DESCRIPTORS, catalog, {
+		const fields = withDirectoryBrowse(applyCatalog(FIELD_DESCRIPTORS, catalog, {
 			provider: effective.provider,
 			model: effective.model,
 			reasoningEffort: effective.reasoningEffort,
 			agentPreset: effective.agentPreset
-		});
+		}), this.directoryPicker?.available === true);
 		let credentialStates = {
 			appId: {
 				configured: false,
@@ -9573,7 +10345,7 @@ var SettingsSurface = class {
 		try {
 			cleanup = await this.target.cleanupPreview();
 		} catch (error) {
-			this.logger?.warn?.("dsh-channels: 工作区清理预览失败：%s", messageOf$1(error));
+			this.logger?.warn?.("dsh-channels: 目录清理预览失败：%s", messageOf$1(error));
 			cleanup = {
 				retention: effective.workspaceRetention,
 				auto: effective.workspaceRetentionAuto,
@@ -9591,6 +10363,7 @@ var SettingsSurface = class {
 			access = {
 				mode: effective.accessMode,
 				admin: { configured: false },
+				loaded: false,
 				groups: [],
 				users: [],
 				requests: []
@@ -9614,6 +10387,8 @@ var SettingsSurface = class {
 	}
 	/** Validate + persist a partial edit; live fields take effect immediately. */
 	async save(values) {
+		const busy = this.writeBusy();
+		if (busy !== void 0) return busy;
 		const unknown = Object.keys(values).filter((key) => !EDITABLE_KEYS.includes(key));
 		if (unknown.length > 0) return {
 			ok: false,
@@ -9696,6 +10471,8 @@ var SettingsSurface = class {
 	}
 	/** Drop every Web override and fall back to the profile config. */
 	async clear() {
+		const busy = this.writeBusy();
+		if (busy !== void 0) return busy;
 		try {
 			await this.store.clear();
 		} catch (error) {
@@ -9712,6 +10489,8 @@ var SettingsSurface = class {
 	}
 	/** Write provided credential values through the host seam (never echoed back). */
 	async saveCredentials(values) {
+		const busy = this.writeBusy();
+		if (busy !== void 0) return busy;
 		const writes = [];
 		const issues = [];
 		for (const field of ["appId", "appSecret"]) {
@@ -9751,6 +10530,8 @@ var SettingsSurface = class {
 	}
 	/** Remove the stored value behind one credential reference. */
 	async clearCredential(field) {
+		const busy = this.writeBusy();
+		if (busy !== void 0) return busy;
 		if (field !== "appId" && field !== "appSecret") return {
 			ok: false,
 			error: "未知的凭据字段"
@@ -9766,9 +10547,11 @@ var SettingsSurface = class {
 		return this.finishCredentialChange("clear");
 	}
 	/**
-	* Credential values are resolved on connect. When the channel is stopped,
-	* retry immediately (nothing to interrupt); when it is running, ask the user
-	* to reconnect. A failed retry still reports the save as successful.
+	* Credential values are resolved on connect. Opening a connection is gated on
+	* readiness: saving one half of the pair stores the value but keeps the
+	* plugin idle until the other half exists. When the channel is stopped and
+	* the pair is complete, connect immediately (nothing to interrupt); when it
+	* is running, the user reconnects to pick the value up.
 	*/
 	async finishCredentialChange(kind) {
 		if (this.target.isRunning()) return {
@@ -9776,13 +10559,13 @@ var SettingsSurface = class {
 			panel: await this.panel(),
 			reconnect: "pending"
 		};
-		if (kind === "clear") return {
+		if (kind === "clear" || !this.target.isConfigured()) return {
 			ok: true,
 			panel: await this.panel(),
-			reconnect: "not-needed"
+			reconnect: kind === "clear" ? "not-needed" : "unconfigured"
 		};
 		try {
-			await this.target.restart();
+			await this.target.connect();
 			return {
 				ok: true,
 				panel: await this.panel(),
@@ -9792,21 +10575,39 @@ var SettingsSurface = class {
 			return {
 				ok: true,
 				panel: await this.panel(),
-				reconnect: "auto",
+				reconnect: "failed",
 				autoReconnectError: messageOf$1(error)
 			};
 		}
 	}
-	/** Close and reopen the Feishu long connection with the latest config. */
+	/**
+	* The panel's single connect/reconnect action: reopen a running connection,
+	* or open the first one when the channel is stopped. Credentials must be
+	* complete — otherwise the panel points the user back at the credentials form
+	* instead of surfacing a startup error.
+	*/
 	async reconnect() {
+		await this.syncReadiness();
+		if (!this.target.isConfigured()) return {
+			ok: false,
+			error: "飞书应用凭据尚未配置完整，请先填写 App ID 与 App Secret 并保存",
+			unconfigured: true
+		};
+		const wasRunning = this.target.isRunning();
 		try {
-			await this.target.restart();
+			if (wasRunning) await this.target.restart();
+			else await this.target.connect();
 		} catch (error) {
 			return {
 				ok: false,
-				error: `重连失败：${messageOf$1(error)}`
+				error: `${wasRunning ? "重连" : "连接"}失败：${messageOf$1(error)}`
 			};
 		}
+		if (!this.target.isRunning()) return {
+			ok: false,
+			unconfigured: !this.target.isConfigured(),
+			error: this.target.startError() ?? (this.target.isConfigured() ? "飞书连接未建立" : "飞书应用凭据尚未配置完整，请先填写并保存凭据")
+		};
 		return {
 			ok: true,
 			panel: await this.panel()
@@ -9890,11 +10691,24 @@ var SettingsSurface = class {
 		}
 	}
 	/**
+	* Open the host's native directory chooser (the panel's「选择目录…」button).
+	*
+	* @param signal - caller lifetime; abort closes the OS dialog.
+	* @returns the chosen absolute path, or `null` when the operator cancels.
+	* @throws when the host provides no native directory chooser.
+	*/
+	async pickDirectory(signal) {
+		if (this.directoryPicker === void 0) throw new Error(PANEL_COPY.directoryPickFailed);
+		return await this.directoryPicker.pick(signal);
+	}
+	/**
 	* Run the workspace-retention cleanup once. Irreversible deletions are the
 	* target's responsibility; the surface only reports the outcome and returns
 	* a refreshed panel (its cleanup preview then reflects the remaining workspaces).
 	*/
 	async runCleanup() {
+		const busy = this.writeBusy();
+		if (busy !== void 0) return busy;
 		let result;
 		try {
 			result = await this.target.runWorkspaceCleanup();
@@ -10158,6 +10972,68 @@ function createHostCatalog(ctx, warn) {
 	} };
 }
 //#endregion
+//#region src/settings/directory-picker.ts
+/** 取出 native 能力；服务缺失、后端为 browse 或 capability 抛错都返回 undefined。 */
+function nativeCapability(service) {
+	if (service === void 0 || typeof service.capability !== "function") return void 0;
+	let capability;
+	try {
+		capability = service.capability();
+	} catch {
+		return;
+	}
+	if (typeof capability !== "object" || capability === null) return void 0;
+	const record = capability;
+	if (record.kind !== "native" || typeof record.pick !== "function") return void 0;
+	return capability;
+}
+/**
+* 从宿主上下文取出可用的系统目录选择器。
+*
+* 解析是**惰性**的：插件可能先于 `dsh-web-app` 的 directory-picker 行完成
+* apply，而设置面板只会在宿主全部加载完成后被请求。因此 `available` 与
+* `pick()` 每次都按需解析（成功结果缓存；失败不缓存，晚挂载的服务仍能被
+* 发现），避免把加载时序固化成「永远没有按钮」。
+*
+* @param ctx - 宿主上下文；`ctx.get('directoryPicker')` 是可选服务。
+* @returns picker；`available` 为 false 时面板保留手写输入。
+*/
+function createSettingsDirectoryPicker(ctx) {
+	let resolved;
+	const resolve = () => {
+		if (resolved !== void 0) return resolved;
+		try {
+			const service = ctx.get?.("directoryPicker");
+			resolved = nativeCapability(service);
+		} catch {
+			resolved = void 0;
+		}
+		return resolved;
+	};
+	/** 互斥：一个原生模态框同时只应存在一个（双击/多标签页不得叠窗）。 */
+	let picking = false;
+	return {
+		get available() {
+			return resolve() !== void 0;
+		},
+		async pick(signal) {
+			const capability = resolve();
+			if (capability === void 0) throw new Error("当前宿主机不提供系统目录选择器");
+			if (picking) throw new Error("已有目录选择窗口正在打开");
+			if (signal.aborted) return null;
+			picking = true;
+			try {
+				const picked = await capability.pick.call(capability, signal);
+				if (picked === null || picked === void 0) return null;
+				if (typeof picked !== "string" || picked.trim() === "") throw new Error("目录选择器返回了无效路径");
+				return picked;
+			} finally {
+				picking = false;
+			}
+		}
+	};
+}
+//#endregion
 //#region src/index.ts
 /** Cordis function-plugin name. */
 const name = "channels";
@@ -10188,7 +11064,7 @@ const inject = [
 * its `resolveConfig()` fallback for direct invocation (unit tests, embedded
 * hosts) where config has not been pre-validated.
 */
-const Config = configSchema;
+const Config = pluginConfigSchema;
 /**
 * Install the bridge. Credentials stay references here — the actual secrets
 * resolve through `ctx.credentials` (env > `$DSH_HOME/.credentials.yaml`
@@ -10202,16 +11078,16 @@ function apply(ctx, config) {
 	const warn = (message, ...args) => {
 		ctx.logger?.warn?.(message, ...args);
 	};
-	mountSettingsRoutes(ctx, new SettingsSurface(service, overlay, { warn }, createHostCatalog(ctx, warn)));
+	mountSettingsRoutes(ctx, new SettingsSurface(service, overlay, { warn }, createHostCatalog(ctx, warn), createSettingsDirectoryPicker(ctx)));
 	ctx.effect(() => {
 		service.boot().catch((error) => {
-			ctx.logger?.error?.("dsh-channels failed to start: %s", String(error));
-			console.error("[dsh-channels] failed to start:", error);
+			ctx.logger?.error?.("dsh-channels failed to boot: %s", String(error));
+			console.error("[dsh-channels] failed to boot:", error);
 		});
 		return () => service.shutdown();
 	}, "dsh-channels");
 }
 //#endregion
-export { AccessController, AccessRequests, AccessStore, ApprovalAnswerer, CARD_MAX_BYTES, CARD_PANEL_RESERVE_BYTES, CARD_TARGET_BYTES, CATALOG_ROUTE, CHANNEL_COMMAND_NAMES, CLEANUP_ROUTE, CONFIG_ROUTE, CREDENTIALS_ROUTE, Config, DM_DENY_TEXT, DM_UNCONFIGURED_TEXT, DSH_CHANNELS_VERSION, EDITABLE_KEYS, EMPTY_TOTALS, FIELD_DESCRIPTORS, FeishuService, HEALTH_DEPENDENCY_NAMES, INTERRUPTION_NOTICE, LOGICAL_EXPORT_FORMAT, LOGICAL_EXPORT_FORMAT_VERSION, MAX_QUESTION_OPTIONS, MAX_TABLES_PER_CARD, OverlayStore, PANEL_CHEVRON_TOKEN, PANEL_COPY, PANEL_ROUTE, PANEL_TITLES, QuestionAnswerer, REASONING_MAX_BYTES, RECONNECT_ROUTE, RESTART_KEYS, RouteOperationQueue, SESSION_HISTORY_DISPLAY_LIMIT, STATUS_ROUTE, SUPPORTED_COMMAND_NAMES, SettingsSurface, TRUNCATION_SUFFIX, TurnStreamer, accessGroupRecordSchema, accessRequestRecordSchema, accessUserRecordSchema, addUsage, appendSessionHistory, apply, applyCatalog, applyProjectionViews, armModelCommand, averageDecodeTokensPerSecond, averageTtftMs, buildApprovalCard, buildApprovalSettledCard, buildCard, buildCommandResultCard, buildCompactComparisonCard, buildGroupInfoCard, buildHealthCard, buildInterruptionCard, buildQuestionCard, buildQuestionSettledCard, buildRenewCard, buildRequestSettledCard, buildSessionHistoryCard, buildSessionStatusCard, buildUserRequestCard, buildWorkDirCard, cacheHitPct, cardJsonBytes, chatRouteKey, commandResultCardKind, compactFailureContext, countFiberStates, createHostCatalog, createLogicalSessionExport, decideAccess, defaultOverlayPath, emptyCatalog, ensureWorkspace, expiredRouteRecordSchema, feishuDomain, foldAll, foldEvent, foldHealthSnapshot, foldSessionStats, inflightSnapshotSchema, inject, isAdminOpenId, isSameOriginRequest, isSupportedCommand, maskOpenIdTail, measureSessionContext, mergeOverlay, mountSettingsRoutes, name, normalizeCredentialValue, normalizeOverlay, normalizeRouteRecord, normalizeSessionHistory, parseOverlay, parseSlashCommand, pickEditable, processedRecordSchema, querySessionHistory, readOnlyFields, readProjectionViews, registerChannelCommands, registerModelCommand, registerSettingsRoutes, resolveDshHome, resolveWorkDir, routeRecordSchema, segmentCardContent, serializeLogicalSession, sessionHistoryEntrySchema, splitBodyForCard, stagingPathFor, stripTables, supportedCommandHelp, supportedCommandList, tableBlocks, topicTokenFor, usageFromBuckets, workspacePathFor, workspaceTitleFor };
+export { AccessController, AccessRequests, AccessStore, ApprovalAnswerer, CARD_MAX_BYTES, CARD_TARGET_BYTES, CATALOG_ROUTE, CHANNEL_COMMAND_NAMES, CLEANUP_ROUTE, CONFIG_ROUTE, CREDENTIALS_ROUTE, Config, DM_DENY_TEXT, DM_UNCONFIGURED_TEXT, DSH_CHANNELS_VERSION, EDITABLE_KEYS, EMPTY_TOTALS, FIELD_DESCRIPTORS, FeishuService, HEALTH_DEPENDENCY_NAMES, INTERRUPTION_NOTICE, LOGICAL_EXPORT_FORMAT, LOGICAL_EXPORT_FORMAT_VERSION, MAX_QUESTION_OPTIONS, MAX_TABLES_PER_CARD, OverlayStore, PANEL_CHEVRON_TOKEN, PANEL_COPY, PANEL_ROUTE, PANEL_TITLES, PICK_DIRECTORY_ROUTE, QuestionAnswerer, REASONING_MAX_BYTES, RECONNECT_ROUTE, RESTART_KEYS, RouteOperationQueue, SESSION_HISTORY_DISPLAY_LIMIT, STATUS_ROUTE, SUPPORTED_COMMAND_NAMES, SettingsSurface, TRUNCATION_SUFFIX, TurnStreamer, accessGroupRecordSchema, accessRequestRecordSchema, accessUserRecordSchema, addUsage, appendSessionHistory, apply, applyCatalog, applyProjectionViews, armModelCommand, averageDecodeTokensPerSecond, averageTtftMs, buildApprovalCard, buildApprovalSettledCard, buildCard, buildCommandResultCard, buildCompactComparisonCard, buildGroupInfoCard, buildHealthCard, buildInterruptionCard, buildQuestionCard, buildQuestionSettledCard, buildRenewCard, buildRequestSettledCard, buildSessionHistoryCard, buildSessionStatusCard, buildUserRequestCard, buildWorkDirCard, cacheHitPct, cardJsonBytes, chatRouteKey, commandResultCardKind, compactFailureContext, countFiberStates, createHostCatalog, createLogicalSessionExport, createSettingsDirectoryPicker, decideAccess, defaultOverlayPath, emptyCatalog, ensureWorkspace, expiredRouteRecordSchema, feishuDomain, foldAll, foldEvent, foldHealthSnapshot, foldSessionStats, inflightSnapshotSchema, inject, isAdminOpenId, isSameOriginRequest, isSupportedCommand, legacyTopicWorkspaceRoot, maskOpenIdTail, measureSessionContext, mergeOverlay, mountSettingsRoutes, name, normalizeCredentialValue, normalizeOverlay, normalizeRouteRecord, normalizeSessionHistory, parseOverlay, parseSlashCommand, pickEditable, processedRecordSchema, querySessionHistory, readOnlyFields, readProjectionViews, registerChannelCommands, registerModelCommand, registerSettingsRoutes, resolveDshHome, resolveWorkDir, routeRecordSchema, segmentCardContent, serializeLogicalSession, sessionDirOf, sessionHistoryEntrySchema, splitBodyForCard, stagingPathFor, stripTables, supportedCommandHelp, supportedCommandList, tableBlocks, topicDirFor, topicTokenFor, usageFromBuckets, withDirectoryBrowse, workspacePathFor, workspaceTitleFor, worktreeBranchFor };
 
 //# sourceMappingURL=index.js.map