@modesto_ma/dsh-channels 0.2.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;
 }
-/** Raw card assembly — no clipping of any kind (the budget machinery wraps this). */
-function assemble(phase, reasoning, body, stats, options, status, tool) {
+/**
+* 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() !== "";
+}
+/** 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;
-}
-/**
-* 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 ?? "");
-	};
+/** 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 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.
+*
+* Conversations produce files below two kinds of directories the host never
+* removes on its own:
 *
-* 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.
+* 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.
 *
-* Activity precedence for one 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.
 *
-* 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).
+* Activity precedence:
 *
-* 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.
+* 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).
-*
-* 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>/`
+* Per-topic Session placement: which directory each Feishu conversation works
+* in, without growing the host workspace list with every topic.
 *
-* 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.
+* 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.
 *
-* Feishu ids (`ou_…`, `oc_…`) are safe path segments, but they are validated
-* anyway so a hostile id can never escape `baseDir`.
+* This module plans one topic's placement:
 *
-* @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.
+* - `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.
 *
-* 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.
+* 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.
 *
-* @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;
-}
 /**
-* 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).
+* 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.
 */
-function topicTokenFor(routeKey, kind, sessionId) {
-	return kind === "thread" ? safeSegment(routeKey, "route key") : safeSegment(sessionId, "session id");
+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";
 }
 /**
-* 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>/`
+* Decide how a new Session is placed and materialize everything that must
+* exist before the Session is created.
 *
-* 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.
+* 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 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);
+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 };
 }
 /**
-* 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.
+* 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.
+*
+* 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: "当前飞书路由未记录可用的工作区目录；请检查路由持久化状态。"
+	};
+	if (route.sessionDir !== void 0 && !path.isAbsolute(route.sessionDir)) return {
 		kind: "missing",
-		text: "当前飞书路由未记录可用的绝对工作目录；请检查路由持久化状态。"
+		text: "当前飞书路由未记录可用的会话目录；请检查路由持久化状态。"
 	};
-	if (headerCwd !== routeWorkspacePath) return {
+	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;
@@ -6922,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;
@@ -6961,15 +7373,21 @@ 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: []
@@ -6980,11 +7398,11 @@ var FeishuService = class {
 		};
 		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 {
@@ -6992,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}`)
@@ -7023,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);
@@ -7065,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.
@@ -7077,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();
@@ -7794,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;
 		}
@@ -7812,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()
@@ -7821,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;
@@ -8338,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
@@ -8363,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),
 	/**
@@ -8465,7 +8964,7 @@ const CREDENTIALS_ROUTE = "/dsh-channels/credentials";
 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";
@@ -8493,7 +8992,7 @@ const PICK_DIRECTORY_ROUTE = "/dsh-channels/pick-directory";
 * 因此不会落进覆盖层文件。
 *
 * `baseDir`（工作区根目录 = 模型/工具产生文件的落点）可覆盖，但面板只接受
-* **绝对路径**（`~` 会展开）；已有 Session / 工作区不迁移，只影响之后新建的
+* **绝对路径**（`~` 会展开）；已有 Session / 目录不迁移，只影响之后新建的
 * 会话。校验与保存时建目录见 `src/workspaces.ts`。
 */
 const EDITABLE_KEYS = [
@@ -8593,7 +9092,7 @@ const PANEL_COPY = {
 	connectionTabHelp: "连接状态与飞书应用凭据。凭据不完整时不会连接飞书。",
 	sessionsTabHelp: "私聊、群聊触发方式与入站内容；「需重连」项在下次连接时读取。",
 	modelTabHelp: "飞书会话使用的模型服务商、模型、推理档位与 Agent 预设；下拉选项来自宿主机实时目录，保存后对新会话生效。",
-	workspaceTabHelp: "每个飞书话题一个独立工作区（模型/工具产生文件的落点）；只影响之后新建的话题。",
+	workspaceTabHelp: "每个用户一个工作区（模型/工具产生文件的落点），每个话题在其中拥有独立工作目录；只影响之后新建的话题。",
 	accessTabHelp: "准入采用 fail-closed：管理员不受白名单限制，非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。",
 	advancedTabHelp: "流式刷新等低层参数、Web 覆盖文件与只读信息。",
 	save: "保存更改",
@@ -8639,11 +9138,12 @@ const PANEL_COPY = {
 	advancedCard: "只读与高级信息",
 	advancedHelp: "这些值来自 profile 配置，不能在面板里编辑。",
 	readOnlyCard: "部署级参数",
-	cleanupCard: "工作区清理",
-	cleanupCardHelp: "删除超过保留期且不再活跃的飞书工作区目录；只会删除本插件在「工作区根目录」下创建的目录，DSH 会话日志不删除。删除不可恢复：相关旧话题会失效并提示已过期，工作区列表记录同步移除。",
+	cleanupCard: "目录清理",
+	cleanupCardHelp: "删除超过保留期且不再活跃的飞书话题目录（以及旧版本按话题建立的工作区目录）；用户工作区本身、DSH 会话日志都不会删除。删除不可恢复：相关旧话题会失效并提示已过期。",
 	cleanupRetention: "保留期",
 	cleanupAutoLabel: "自动清理",
-	cleanupCandidates: "可清理工作区",
+	cleanupCandidates: "可清理目录",
+	cleanupWorkspaces: "插件工作区",
 	cleanupCandidateBytes: "预计释放空间",
 	cleanupRetentionOff: "关闭（不删除）",
 	cleanupAutoOn: "已开启（启动时 + 每天一次）",
@@ -8651,17 +9151,18 @@ 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：管理员不受白名单限制（私聊、任意群聊都可直接对话）；非管理员私聊会被拒绝，群聊需要「群已授权 + 用户在白名单」两层同时命中。管理员与准入模式在上方「准入与授权」中编辑；私聊机器人发送 /userid 获取自己的 open_id。",
 	accessModeOpenWarning: "当前准入模式为开放（open）：应用可用范围内的任何人都能开启对话。该模式不安全，仅建议调试时使用。",
@@ -9350,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
 	},
@@ -9395,12 +9896,12 @@ const FIELD_META = {
 		help: "接收飞书图片、文件与合并转发记录，保存到工作区的 attachments/ 目录；模型不会自动读取，需要时用文件工具自行查看。关闭后附件消息不保存、不触发回复。"
 	},
 	workspaceRetention: {
-		label: "过期工作区保留期",
-		help: "超过所选天数没有活动的飞书工作区会进入下方「工作区清理」列表；「关闭」表示永不删除。DSH 会话日志不受影响。"
+		label: "过期目录保留期",
+		help: "超过所选天数没有活动的飞书话题目录（以及旧版本按话题建立的工作区目录）会进入下方清理列表；用户工作区本身永不删除。DSH 会话日志不受影响。"
 	},
 	workspaceRetentionAuto: {
-		label: "自动执行工作区清理",
-		help: "开启后插件在启动时及每天执行一次过期工作区清理；关闭时只能在下方卡片手动清理。开启前请确认保留期已设置。"
+		label: "自动执行目录清理",
+		help: "开启后插件在启动时及每天执行一次过期目录清理；关闭时只能在下方卡片手动清理。开启前请确认保留期已设置。"
 	},
 	provider: {
 		label: "模型服务商",
@@ -9664,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: "话题路由过期",
@@ -9838,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,
@@ -10581,6 +11088,6 @@ function apply(ctx, config) {
 	}, "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, 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, 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, withDirectoryBrowse, 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