@modesto_ma/dsh-channels 0.1.0 → 0.3.0

package/src/config.ts

@@ -21,6 +21,10 @@ export type FeishuLoggerLevel = (typeof FEISHU_LOGGER_LEVELS)[number]
 /** Same shape as the host credentials seam's `CredentialRef` (shell identifier). */
 export const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
 
+/** Conventional credential-reference names used when the loader passes no config. */
+export const DEFAULT_APP_ID_REF = 'FEISHU_APP_ID'
+export const DEFAULT_APP_SECRET_REF = 'FEISHU_APP_SECRET'
+
 /** Default route-table GC threshold: 30 days without activity. */
 export const DEFAULT_ROUTE_TTL_MS = 30 * 24 * 60 * 60 * 1000
 
@@ -37,10 +41,10 @@ const credentialRefSchema = z.string().regex(
 )
 
 export const configSchema = z.object({
-  /** Feishu app id credential reference (e.g. `FEISHU_APP_ID`). */
-  appId: credentialRefSchema,
-  /** Feishu app secret credential reference (e.g. `FEISHU_APP_SECRET`). */
-  appSecret: credentialRefSchema,
+  /** Feishu app id credential reference (defaults to `FEISHU_APP_ID`). */
+  appId: credentialRefSchema.default(DEFAULT_APP_ID_REF),
+  /** Feishu app secret credential reference (defaults to `FEISHU_APP_SECRET`). */
+  appSecret: credentialRefSchema.default(DEFAULT_APP_SECRET_REF),
   /**
    * Root directory for per-(user, chat) workspace directories — the filesystem
    * root where files produced by channel sessions land. Read per session
@@ -99,6 +103,23 @@ export const configSchema = z.object({
    * `strict` fails the reply instead.
    */
   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
@@ -125,17 +146,19 @@ export 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),
   /**
@@ -188,6 +211,15 @@ export const configSchema = z.object({
 
 export type FeishuConfig = z.infer<typeof configSchema>
 
+/**
+ * DSH loader-facing schema. The bundle patch inserts this plugin without a
+ * `config` object; the loader validates that row with `undefined` before the
+ * user's patch layer supplies values. Accept that absence and fill the same
+ * defaults as {@link resolveConfig}, so enabling the plugin from the Web UI
+ * cannot fail with "expected object, received undefined".
+ */
+export const pluginConfigSchema = configSchema.prefault({})
+
 /**
  * Validate the raw loader config. Values stay credential *references*; the
  * secrets themselves resolve through `ctx.credentials` at startup.

package/src/domain.ts

@@ -10,8 +10,16 @@
 
 import { z } from 'zod'
 
-/** Route key kinds. `thread` = real Feishu topic; `chat` = degraded chat-scoped fallback. */
-export const ROUTE_RECORD_VERSION = 1
+/**
+ * Route key kinds. `thread` = real Feishu topic; `chat` = degraded chat-scoped
+ * fallback.
+ *
+ * Version 2 adds the optional `sessionDir` / `worktreeBranch` fields (the
+ * Session's effective working directory). Version-1 records stay readable: an
+ * absent `sessionDir` means the workspace path itself is the working directory
+ * (the pre-v2 model).
+ */
+export const ROUTE_RECORD_VERSION = 2
 
 export const sessionHistoryEntrySchema = z.object({
   /** One Session that has been bound to this route. */
@@ -35,8 +43,16 @@ export 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. */
@@ -71,6 +87,12 @@ export 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. */
@@ -116,6 +138,15 @@ export function appendSessionHistory(
   })
 }
 
+/**
+ * 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.
+ */
+export function sessionDirOf(record: Pick<RouteRecord, 'workspacePath' | 'sessionDir'>): string {
+  return record.sessionDir ?? record.workspacePath
+}
+
 /**
  * In-flight turn snapshot: everything needed to repair a streaming card that a
  * restart left mid-flight (stuck panel, leftover Typing reaction, never-patched

package/src/feishu/agent-context.ts

@@ -2,12 +2,16 @@
  * Agent-scoped system-prompt guidance for Feishu attachments.
  *
  * The channel archives inbound images/files/forwarded records below
- * `<workspace>/attachments/` without any model turn. This section is what
- * makes that convention discoverable: it tells the Agent where attachments
- * live, how to read them, and that reading is opt-in per user request.
+ * `<session working directory>/attachments/` without any model turn. This
+ * section is what makes that convention discoverable: it tells the Agent where
+ * attachments live, how to read them, and that reading is opt-in per user
+ * request.
  *
  * Registered inside the Agent scope (through `inject(['systemPrompt'])`), so
  * it is disposed with the Agent and does not leak into other compositions.
+ * It is mounted only after the Session's effective working directory is known
+ * (see `SessionManager.mountGuidance`), so the absolute path is accurate even
+ * when that directory is a Git worktree created after Agent creation.
  *
  * @module dsh-channels/feishu/agent-context
  */
@@ -26,13 +30,13 @@ const FEISHU_ATTACHMENTS_ORDER = 950
 
 /** Model-facing text. Kept stable so unchanged sessions keep their KV cache. */
 export 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

package/src/index.ts

@@ -3,19 +3,21 @@
  *
  * 一个 dsh 实例对应一个飞书机器人；用户通过私聊、群聊 @、话题群 @ 三种方式
  * 发起会话。每条触发消息：立即加 “Typing” 表情 → 以话题形式回复（创建话题）
- * → 绑定 DSH session → 卡片 2.0 流式回复（推理折叠面板 + 富文本正文 + 两行
- * session 信息，默认 500ms 刷新）→ 流式结束移除 Typing，成功更新为
+ * → 绑定 DSH session → 卡片 2.0 流式回复（推理折叠面板 + 临时活动行 +
+ * 富文本正文 + 结算页脚，默认 500ms 刷新）→ 流式结束移除 Typing，成功更新为
  * “DONE”，失败显示结构化错误并更新为 “No”。
  *
  * 工作区归属：私聊一人一工作区；群聊中每个用户在该群拥有独立工作区
- * （目录即工作区，会话以 cwd 落盘）。
+ * （工作区是会话 header cwd，保证 GUI 归属与沙箱边界）。每个话题在该工作区
+ * 内拥有独立的工作目录（`topics/<话题>`，Git 仓库工作区可自动改用 worktree），
+ * 因此话题之间的文件互不干扰，而工作区数量只随用户增长。
  *
  * @module dsh-channels
  */
 
 import type { HostContext } from './dsh-types.ts'
 import { FeishuService } from './service.ts'
-import { configSchema, resolveConfig } from './config.ts'
+import { pluginConfigSchema, resolveConfig } from './config.ts'
 import type { FeishuConfig } from './config.ts'
 import { defaultChannelFactory } from './feishu-channel.ts'
 import type { ChannelFactory } from './feishu-channel.ts'
@@ -23,6 +25,7 @@ import { OverlayStore, defaultOverlayPath } from './settings/overlay.ts'
 import { mountSettingsRoutes } from './settings/routes.ts'
 import { SettingsSurface } from './settings/surface.ts'
 import { createHostCatalog } from './settings/catalog.ts'
+import { createSettingsDirectoryPicker } from './settings/directory-picker.ts'
 
 export type * from './config.ts'
 export type * from './cards.ts'
@@ -38,16 +41,19 @@ export type * from './questions.ts'
 export type * from './settings/contract.ts'
 export * from './access/index.ts'
 export type { AccessGroupRecord, AccessRequestRecord, AccessUserRecord } from './domain.ts'
-export { CATALOG_ROUTE, CLEANUP_ROUTE, CONFIG_ROUTE, CREDENTIALS_ROUTE, EDITABLE_KEYS, PANEL_COPY, PANEL_ROUTE, RECONNECT_ROUTE, RESTART_KEYS, STATUS_ROUTE } from './settings/contract.ts'
+export { CATALOG_ROUTE, CLEANUP_ROUTE, CONFIG_ROUTE, CREDENTIALS_ROUTE, EDITABLE_KEYS, PANEL_COPY, PANEL_ROUTE, PICK_DIRECTORY_ROUTE, RECONNECT_ROUTE, RESTART_KEYS, STATUS_ROUTE } from './settings/contract.ts'
+export type { PickDirectoryResponse } from './settings/contract.ts'
 export { defaultOverlayPath, mergeOverlay, normalizeOverlay, OverlayStore, parseOverlay, pickEditable, resolveDshHome } from './settings/overlay.ts'
-export { applyCatalog, emptyCatalog, FIELD_DESCRIPTORS, normalizeCredentialValue, readOnlyFields, SettingsSurface } from './settings/surface.ts'
+export { applyCatalog, emptyCatalog, FIELD_DESCRIPTORS, normalizeCredentialValue, readOnlyFields, SettingsSurface, withDirectoryBrowse } from './settings/surface.ts'
 export type { SettingsTarget } from './settings/surface.ts'
 export { createHostCatalog } from './settings/catalog.ts'
 export type { CatalogWarn, SettingsCatalog } from './settings/catalog.ts'
+export { createSettingsDirectoryPicker } from './settings/directory-picker.ts'
+export type { HostDirectoryPickerService, SettingsDirectoryPicker } from './settings/directory-picker.ts'
 export { isSameOriginRequest, mountSettingsRoutes, registerSettingsRoutes } from './settings/routes.ts'
 export type { HostWebServer } from './settings/routes.ts'
 export type { ApprovalOutcome, ApprovalRequest, ApprovalAnswererListener, AssistantStreamFrame, AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionRequestEvent, UserQuestionAnswererListener, AgentCancelCause, SessionStatsView, TokenUsageView, ContextPressureView, SessionProjections } from './dsh-types.ts'
-export { buildCard, buildInterruptionCard, cardJsonBytes, CARD_MAX_BYTES, CARD_TARGET_BYTES, CARD_PANEL_RESERVE_BYTES, REASONING_MAX_BYTES, INTERRUPTION_NOTICE, MAX_TABLES_PER_CARD, PANEL_TITLES, PANEL_CHEVRON_TOKEN, segmentCardContent, splitBodyForCard, stripTables, tableBlocks, TRUNCATION_SUFFIX, buildApprovalCard, buildApprovalSettledCard, buildQuestionCard, buildQuestionSettledCard, MAX_QUESTION_OPTIONS } from './cards.ts'
+export { buildCard, buildInterruptionCard, cardJsonBytes, CARD_MAX_BYTES, CARD_TARGET_BYTES, REASONING_MAX_BYTES, INTERRUPTION_NOTICE, MAX_TABLES_PER_CARD, PANEL_TITLES, PANEL_CHEVRON_TOKEN, segmentCardContent, splitBodyForCard, stripTables, tableBlocks, TRUNCATION_SUFFIX, buildApprovalCard, buildApprovalSettledCard, buildQuestionCard, buildQuestionSettledCard, MAX_QUESTION_OPTIONS } from './cards.ts'
 export { ApprovalAnswerer } from './approvals.ts'
 export { QuestionAnswerer } from './questions.ts'
 export { armModelCommand, buildCommandResultCard, CHANNEL_COMMAND_NAMES, commandResultCardKind, isSupportedCommand, parseSlashCommand, registerChannelCommands, registerModelCommand, RouteOperationQueue, SUPPORTED_COMMAND_NAMES, supportedCommandHelp, supportedCommandList } from './commands.ts'
@@ -57,8 +63,8 @@ export { createLogicalSessionExport, DSH_CHANNELS_VERSION, LOGICAL_EXPORT_FORMAT
 export { addUsage, applyProjectionViews, averageDecodeTokensPerSecond, averageTtftMs, cacheHitPct, EMPTY_TOTALS, foldAll, foldEvent, foldSessionStats, measureSessionContext, readProjectionViews, usageFromBuckets } from './stats.ts'
 export { FeishuService } from './service.ts'
 export { TurnStreamer } from './streamer.ts'
-export { ensureWorkspace, stagingPathFor, topicTokenFor, workspacePathFor, workspaceTitleFor } from './workspaces.ts'
-export { accessGroupRecordSchema, accessRequestRecordSchema, accessUserRecordSchema, appendSessionHistory, chatRouteKey, expiredRouteRecordSchema, feishuDomain, normalizeRouteRecord, normalizeSessionHistory, routeRecordSchema, sessionHistoryEntrySchema, inflightSnapshotSchema, processedRecordSchema } from './domain.ts'
+export { ensureWorkspace, legacyTopicWorkspaceRoot, stagingPathFor, topicDirFor, topicTokenFor, workspacePathFor, workspaceTitleFor, worktreeBranchFor } from './workspaces.ts'
+export { accessGroupRecordSchema, accessRequestRecordSchema, accessUserRecordSchema, appendSessionHistory, chatRouteKey, expiredRouteRecordSchema, feishuDomain, normalizeRouteRecord, normalizeSessionHistory, routeRecordSchema, sessionDirOf, sessionHistoryEntrySchema, inflightSnapshotSchema, processedRecordSchema } from './domain.ts'
 
 /** Cordis function-plugin name. */
 export const name = 'channels'
@@ -83,7 +89,7 @@ export const inject = ['agents', 'commands', 'workspaceRegistry', 'storageDomain
  * its `resolveConfig()` fallback for direct invocation (unit tests, embedded
  * hosts) where config has not been pre-validated.
  */
-export const Config = configSchema
+export const Config = pluginConfigSchema
 
 export interface FeishuPluginOptions extends FeishuConfig {
   /** Test seam: substitute a channel implementation. */
@@ -106,16 +112,28 @@ export function apply(ctx: HostContext, config?: unknown): void {
   )
   const service = new FeishuService(ctx, resolved, factory, undefined, overlay)
   // Settings routes ride the host's web server when this deployment has one.
-  // The catalog resolves the panel's model selectors from live host services.
+  // The catalog resolves the panel's model selectors from live host services;
+  // the optional native directory picker backs the workspace-root「选择目录…」
+  // button (absent in headless/remote compositions → plain text input).
   const warn = (message: string, ...args: unknown[]): void => { ctx.logger?.warn?.(message, ...args) }
-  mountSettingsRoutes(ctx, new SettingsSurface(service, overlay, { warn }, createHostCatalog(ctx, warn)))
+  mountSettingsRoutes(ctx, new SettingsSurface(
+    service,
+    overlay,
+    { warn },
+    createHostCatalog(ctx, warn),
+    createSettingsDirectoryPicker(ctx),
+  ))
   ctx.effect(() => {
+    // Boot loads the Web overlay and connects only when the Feishu application
+    // credentials are complete; an incomplete configuration or a failed
+    // connection is a panel-visible state, not a plugin failure. Only an
+    // unexpected boot error (e.g. unreadable overlay) reaches this catch.
     void service.boot().catch((error: unknown) => {
-      ctx.logger?.error?.('dsh-channels failed to start: %s', String(error))
+      ctx.logger?.error?.('dsh-channels failed to boot: %s', String(error))
       // Critical lifecycle line duplicated to the console: cordis logger
       // messages emitted before a web exporter attaches are buffered and may
       // never reach stdout, which makes real-device debugging guesswork.
-      console.error('[dsh-channels] failed to start:', error)
+      console.error('[dsh-channels] failed to boot:', error)
     })
     return () => service.shutdown()
   }, 'dsh-channels')

package/src/routing/inbound.ts

@@ -14,7 +14,7 @@ import type { AgentHandle, HostContext, SessionId, UserMessage, Workspace } from
 import type { FeishuConfig } from '../config.ts'
 import { buildCard, buildOnboardingCard, initialStreamingCard } from '../cards.ts'
 import { RouteOperationQueue } from '../commands.ts'
-import { chatRouteKey } from '../domain.ts'
+import { chatRouteKey, sessionDirOf } from '../domain.ts'
 import type { FeishuDomainHandle, RouteRecord } from '../domain.ts'
 import type { CardDelivery } from '../feishu/delivery.ts'
 import {
@@ -28,6 +28,10 @@ import type { InflightRepair } from '../session/repair.ts'
 import type { SessionManager } from '../session/manager.ts'
 import type { RouteStore } from '../session/routes.ts'
 import type { TurnStreamer } from '../streamer.ts'
+import {
+  enterTopic, placementServices, planTopic, restoreTopicDir,
+} from '../session/isolation.ts'
+import type { PlacementServices, TopicPlacement, TopicPlan } from '../session/isolation.ts'
 import { ensureWorkspace, stagingPathFor, topicTokenFor } from '../workspaces.ts'
 
 /** The command plane the inbound router delegates admission-time work to. */
@@ -313,12 +317,12 @@ export class InboundRouter {
 
     return await this.routeOperations.run(record?.key ?? chatKey, async () => {
       if (!this.started) return { saved: 0, failed: 0, failures: [], attachmentOnly: true, text: '' }
-      // An existing topic has a workspace already; a conversation without one
-      // stages files below baseDir until its first Session creates the topic
-      // workspace and adopts them.
+      // An existing topic already has its own working directory; a
+      // conversation without one stages files below baseDir until its first
+      // Session creates the topic directory and adopts them.
       const directory = record === undefined
         ? stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId)
-        : attachmentsDir(record.workspacePath)
+        : attachmentsDir(sessionDirOf(record))
       return await this.attachments.archive(msg, directory)
     })
   }
@@ -395,25 +399,20 @@ export class InboundRouter {
     const initialStats = { sessionId, inputTokens: 0, outputTokens: 0 }
 
     // 2. First card frame — also creates the topic (reply_in_thread). The
-    //    topic identity is only known after Feishu answers, and it decides the
-    //    workspace: every new topic gets its own directory.
+    //    topic identity is only known after Feishu answers, and it names the
+    //    topic's private working directory inside the user's workspace.
     const sent = await this.delivery.replyFirstCard(msg, initialStreamingCard(sessionId))
     const typingId = await typingPromise
     const key = sent.degraded || sent.threadId === undefined ? chatKey : sent.threadId
     const kind = sent.degraded || sent.threadId === undefined ? 'chat' : 'thread'
 
-    // 3. Workspace for this topic, then adopt attachments staged before it.
-    let workspace: 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 = placementServices(this.ctx)
+    const warn = (message: string, ...args: unknown[]): void => {
+      this.ctx.logger?.warn?.(message, ...args)
+    }
+    /** Patch the streaming card to its terminal creation-failure state. */
+    const failCreation = async (error: unknown): Promise<void> => {
       void this.repair.clear(sent.messageId)
       await this.delivery.requireChannel().updateCard(sent.messageId, buildCard({
         phase: 'done',
@@ -421,6 +420,20 @@ export class InboundRouter {
         body: `会话创建失败：${String(error)}`,
         stats: { ...initialStats },
       })).catch(() => {})
+    }
+
+    // 3. User workspace (the durable project this Session is grouped under)
+    //    plus the per-topic placement plan. No Agent exists yet; the plan
+    //    materializes anything that must exist before creation.
+    let workspace: Workspace
+    let plan: TopicPlan
+    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
     }
 
@@ -439,27 +452,39 @@ export class InboundRouter {
       attempts: 0,
     })
 
-    // 4. Create the agent/session bound to the workspace directory.
-    let handle: AgentHandle
+    // 4. Create the Session (header cwd = user workspace when directories can
+    //    be switched), then enter its own topic directory / worktree.
+    let handle: AgentHandle | undefined
+    let placement: TopicPlacement | undefined
     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)
+      // A workspace attachment only validates when the header cwd is the
+      // workspace itself; the hard fallback (no workingDirectory service) must
+      // skip it instead of logging a guaranteed failure.
+      if (plan.cwd === workspace.path) {
+        void Promise.resolve(workspace.attachSession(sessionId)).catch((error: unknown) => {
+          warn('dsh-channels: attaching initial session %s to workspace failed: %s', sessionId, String(error))
+        })
+      }
+      // Files staged before this topic existed belong to this conversation.
+      await adoptStagedAttachments(
+        stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId),
+        placement.sessionDir,
+      ).catch((error: unknown) => {
+        warn('dsh-channels: adopting staged attachments failed: %s', String(error))
+      })
+      await this.sessions.mountGuidance(handle.agent, placement.sessionDir)
     } catch (error) {
-      // The card lands in a final failure state — no repair needed later.
-      void this.repair.clear(sent.messageId)
-      await this.delivery.requireChannel().updateCard(sent.messageId, buildCard({
-        phase: 'done',
-        reasoning: '',
-        body: `会话创建失败：${String(error)}`,
-        stats: { ...initialStats },
-      })).catch(() => {})
+      // The card lands in a final failure state — no repair needed later. A
+      // Session created just before the failure must not stay live unnoticed.
+      await handle?.dispose().catch(() => {})
+      await failCreation(error)
       throw error
     }
-    void 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 === undefined || placement === undefined) {
+      throw new Error('dsh-channels: session creation completed without a handle')
+    }
 
     // 5. Persist the route (thread-scoped, or degraded chat-scoped).
     const createdAt = handle.agent.session.header.createdAt
@@ -471,6 +496,8 @@ export class InboundRouter {
       chatType: msg.chatType,
       senderOpenId: msg.senderId,
       workspacePath: workspace.path,
+      sessionDir: placement.sessionDir,
+      ...(placement.worktreeBranch === undefined ? {} : { worktreeBranch: placement.worktreeBranch }),
       cardMessageId: sent.messageId,
       createdAt,
       lastActivityAt: createdAt,
@@ -487,24 +514,42 @@ export class InboundRouter {
     // Defence in depth: every current caller checks this first, but a future
     // call path must not be able to continue another user's Session.
     if (!this.access.ownsRoute(msg, record)) return
+    const services = placementServices(this.ctx)
+    const warn = (message: string, ...args: unknown[]): void => {
+      this.ctx.logger?.warn?.(message, ...args)
+    }
+    const typingPromise = this.delivery.requireChannel().addReaction(msg.messageId, 'Typing').catch(() => undefined)
+    const live = await this.sessions.ensureLive(record)
+    // The topic directory can disappear independently of the Session (manual
+    // deletion, external cleanup). Recreate it and re-align the effective
+    // working directory so the turn never leaks into the shared workspace root.
+    const placement = await restoreTopicDir(services, live.agent, {
+      workspacePath: record.workspacePath,
+      sessionDir: sessionDirOf(record),
+      ...(record.worktreeBranch === undefined ? {} : { worktreeBranch: record.worktreeBranch }),
+    }, warn)
+    let current: RouteRecord = record
+    if (placement.sessionDir !== sessionDirOf(record) || placement.worktreeBranch !== record.worktreeBranch) {
+      current = { ...record, sessionDir: placement.sessionDir }
+      delete current.worktreeBranch
+      if (placement.worktreeBranch !== undefined) current = { ...current, worktreeBranch: placement.worktreeBranch }
+    }
     // Files staged before this conversation's topic existed follow its next
     // turn (for example a file sent in the chat before the first prompt).
     await adoptStagedAttachments(
       stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId),
-      record.workspacePath,
+      placement.sessionDir,
     ).catch((error: unknown) => {
       this.ctx.logger?.warn?.('dsh-channels: adopting staged attachments failed: %s', String(error))
     })
-    const typingPromise = this.delivery.requireChannel().addReaction(msg.messageId, 'Typing').catch(() => undefined)
-    const live = await this.sessions.ensureLive(record)
 
-    const sent = await this.delivery.replyFirstCard(msg, initialStreamingCard(record.sessionId))
+    const sent = await this.delivery.replyFirstCard(msg, initialStreamingCard(current.sessionId))
     const typingId = await typingPromise
 
     // Repair snapshot first — same crash-window reasoning as `startSession`.
     await this.repair.write({
       key: sent.messageId,
-      sessionId: record.sessionId,
+      sessionId: current.sessionId,
       chatId: msg.chatId,
       triggerMessageId: msg.messageId,
       reactionId: typingId,
@@ -513,8 +558,8 @@ export class InboundRouter {
       attempts: 0,
     })
 
-    await this.routes.put(record.key, {
-      ...record,
+    await this.routes.put(current.key, {
+      ...current,
       cardMessageId: sent.messageId,
       lastActivityAt: Date.now(),
     })