@modesto_ma/dsh-channels 0.1.0 → 0.3.0

package/src/cleanup.ts

@@ -1,35 +1,38 @@
 /**
- * Stale workspace cleanup: pure planning and application policy.
+ * Retention cleanup policy: pure planning and application over injected seams.
  *
- * The plugin creates one host workspace per (user × chat) pair below its
- * configured `baseDir` (see `workspaces.ts`). The host never removes those
- * directories on its own, so a long-running deployment slowly accumulates
- * attachments and agent output for conversations nobody uses anymore. This
- * module decides which plugin-created workspaces are stale and applies the
- * removal while deliberately owning no I/O: every filesystem and registry
- * effect is injected through `CleanupDeps`, which keeps the policy small and
- * testable and keeps the dangerous half (recursive deletion + registry
- * unregistration) in the caller.
+ * Conversations produce files below two kinds of directories the host never
+ * removes on its own:
  *
- * Activity precedence for one workspace:
+ * 1. **Per-topic session directories** (current layout): the effective working
+ *    directory of one Feishu topic — `<user-workspace>/topics/<token>` or a Git
+ *    worktree checkout. They are not registered workspaces, so their activity
+ *    comes from route records/tombstones or from the directory's own `mtime`.
+ * 2. **Legacy one-workspace-per-topic directories** written by older plugin
+ *    versions (`<baseDir>/topics/...`). Those are still registered host
+ *    workspaces and are unregistered when removed.
  *
- * 1. the newest `lastActivityAt` among its active routes; a workspace with a
- *    live session is never offered for deletion,
- * 2. otherwise the newest tombstone that names the workspace
- *    (`lastActivityAt`, falling back to `expiredAt` for tombstones written
- *    before routes recorded their workspace path),
- * 3. otherwise the directory's own `mtime` (an orphan workspace).
+ * User workspaces themselves (the durable project each user/chat is grouped
+ * under) are never candidates. This module owns no I/O: every filesystem and
+ * registry effect is injected through `CleanupDeps`, so the policy stays small
+ * and testable while the dangerous half (recursive deletion + registry
+ * unregistration) stays in the caller.
  *
- * Tombstones written before this feature carry neither `workspacePath` nor
- * `lastActivityAt`, so they cannot be attributed to a workspace; such a
- * workspace falls through to the `mtime` rule instead. A workspace with no
- * usable activity evidence at all (missing or unreadable directory) is never
- * offered for deletion: irreversible removal requires positive evidence.
+ * Activity precedence:
+ *
+ * 1. the newest `lastActivityAt` among the active routes bound to the target;
+ *    a target with a live Session is never offered for deletion,
+ * 2. otherwise the newest tombstone that names it,
+ * 3. otherwise the directory's own `mtime` (an orphan directory).
+ *
+ * A directory with no usable activity evidence at all (missing/unreadable) is
+ * never offered for deletion: irreversible removal requires positive evidence.
  *
  * @module dsh-channels/cleanup
  */
 
 import path from 'node:path'
+import { legacyTopicWorkspaceRoot } from './workspaces.ts'
 
 /** Values the `workspaceRetention` config accepts. `off` disables cleanup. */
 export const WORKSPACE_RETENTION_VALUES = ['off', '7d', '30d', '90d', '180d'] as const
@@ -60,6 +63,14 @@ export function retentionMs(value: WorkspaceRetention): number | undefined {
 /** Title prefixes `workspaces.ts` gives plugin-created workspaces. */
 const PLUGIN_TITLE_PREFIXES = ['飞书私聊 ·', '飞书群聊 ·'] as const
 
+/**
+ * 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: string): boolean {
+  return PLUGIN_TITLE_PREFIXES.some(prefix => title.startsWith(prefix))
+}
+
 /**
  * Whether `target` is strictly below `baseDir`.
  *
@@ -67,8 +78,8 @@ const PLUGIN_TITLE_PREFIXES = ['飞书私聊 ·', '飞书群聊 ·'] as const
  * 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.
@@ -83,9 +94,9 @@ export function isPathInside(baseDir: string, target: string): boolean {
   return relative !== '..' && !relative.startsWith(`..${path.sep}`)
 }
 
-/** Filesystem facts the caller measures for one workspace candidate. */
+/** Filesystem facts the caller measures for one candidate directory. */
 export interface WorkspaceStats {
-  /** Directory mtime in epoch ms — the activity fallback for orphan workspaces. */
+  /** Directory mtime in epoch ms — the activity fallback for orphan directories. */
   mtimeMs: number
   /** Total regular-file bytes below the directory. */
   bytes: number
@@ -93,7 +104,7 @@ export interface WorkspaceStats {
   files: number
 }
 
-/** Minimal workspace shape passed around by plan/apply (structurally `Workspace`). */
+/** One registered host workspace (structurally `Workspace`). */
 export interface CleanupWorkspace {
   /** Host workspace-registry id (needed to unregister the record). */
   readonly id: string
@@ -109,8 +120,10 @@ export interface CleanupRoute {
   readonly key: string
   /** `thread` for a real Feishu topic, `chat` for a degraded chat route. */
   readonly kind: 'thread' | 'chat'
-  /** Workspace directory this route's session works in. */
+  /** Workspace root this route's Session belongs to. */
   readonly workspacePath: string
+  /** Effective working directory (topic dir / worktree); the workspace path on legacy routes. */
+  readonly sessionDir?: string
   /** DSH session the route points at. */
   readonly sessionId: string
   /** Epoch ms of the last activity routed through the record. */
@@ -120,30 +133,50 @@ export interface CleanupRoute {
 /**
  * One retired-route tombstone.
  *
- * Older plugin versions stored only route identity, so `workspacePath` and
- * `lastActivityAt` stay optional and legacy tombstones remain parseable.
+ * Older plugin versions stored only route identity, so `workspacePath`,
+ * `sessionDir`, and `lastActivityAt` stay optional and legacy tombstones
+ * remain parseable.
  */
 export interface CleanupTombstone {
   /** Route key the tombstone replaced. */
   readonly key: string
   /** Workspace the retired route belonged to; absent in legacy tombstones. */
   readonly workspacePath?: string
+  /** Effective working directory of the retired route; absent in legacy tombstones. */
+  readonly sessionDir?: string
   /** Epoch ms when the route was retired. */
   readonly expiredAt: number
   /** Epoch ms of the last activity before retirement; absent in legacy tombstones. */
   readonly lastActivityAt?: number
 }
 
+/**
+ * One per-topic directory discovered on disk below a live user workspace.
+ * Supplies the age evidence for directories whose route records are gone.
+ */
+export interface ScannedSessionDir {
+  /** Absolute directory path. */
+  readonly path: string
+  /** Directory mtime in epoch ms. */
+  readonly mtimeMs: number
+}
+
 /** A dependency seam that may be sync (registry tables) or async (filesystem). */
 export type MaybePromise<T> = T | Promise<T>
 
+/** What one cleanup candidate removes. */
+export type CleanupTarget =
+  | { readonly kind: 'workspace'; readonly workspace: CleanupWorkspace }
+  | { readonly kind: 'session-dir'; readonly path: string }
+
 /**
  * Every effect cleanup needs, injected so this module stays I/O-free.
  *
  * The service supplies the real implementations: the workspace registry for
  * `listWorkspaces`/`removeWorkspace`, the routing tables for
- * `activeRoutes`/`tombstones`, the live-agent set for `isLive`, and a
- * filesystem walk for `statWorkspace`.
+ * `activeRoutes`/`tombstones`, a scan of the live user workspaces for
+ * `listSessionDirs`, the live-agent set for `isLive`, and filesystem walks for
+ * `statWorkspace` plus the two removal operations.
  */
 export interface CleanupDeps {
   /** Workspace root the plugin owns; candidates must be strictly inside it. */
@@ -152,16 +185,20 @@ export interface CleanupDeps {
   readonly retention: WorkspaceRetention
   /** Every workspace currently registered with the host. */
   listWorkspaces(): MaybePromise<readonly CleanupWorkspace[]>
+  /** Per-topic directories discovered below the live user workspaces. */
+  listSessionDirs(): MaybePromise<readonly ScannedSessionDir[]>
   /** Every active route record. */
   activeRoutes(): MaybePromise<readonly CleanupRoute[]>
   /** Every retired-route tombstone. */
   tombstones(): MaybePromise<readonly CleanupTombstone[]>
-  /** Whether a DSH session is still live; live workspaces are never offered. */
+  /** Whether a DSH session is still live; targets with live sessions are never offered. */
   isLive(sessionId: string): boolean
   /** Measure one directory; `undefined` when it cannot be read (missing, permission). */
-  statWorkspace(workspacePath: string): MaybePromise<WorkspaceStats | undefined>
-  /** Delete one workspace directory and unregister its registry record. */
+  statWorkspace(directory: string): MaybePromise<WorkspaceStats | undefined>
+  /** Delete one legacy workspace directory and unregister its registry record. */
   removeWorkspace(workspace: CleanupWorkspace): MaybePromise<void>
+  /** Delete one per-topic session directory (no registry record exists). */
+  removeSessionDir(directory: string): MaybePromise<void>
   /** Retire one active route into a tombstone (same bookkeeping as route TTL). */
   retireRoute(route: CleanupRoute): MaybePromise<void>
   /** Clock seam; defaults to `Date.now()`. */
@@ -170,117 +207,114 @@ export interface CleanupDeps {
   warn?(message: string): void
 }
 
-/** One workspace old enough to delete, with its measured footprint. */
+/** One directory old enough to delete, with its measured footprint. */
 export interface CleanupCandidate {
-  /** Workspace to delete. */
-  readonly workspace: CleanupWorkspace
-  /** Newest activity observed for the workspace (epoch ms). */
+  /** What gets removed and how. */
+  readonly target: CleanupTarget
+  /** Directory path (also the unit of failure). */
+  readonly path: string
+  /** Newest activity observed for the target (epoch ms). */
   readonly activityAt: number
   /** Regular-file bytes below the directory (0 when unreadable). */
   readonly bytes: number
   /** Regular-file count below the directory (0 when unreadable). */
   readonly files: number
-  /** Active routes still pointing at the workspace; retired before removal. */
+  /** Active routes this candidate's directory owns (retired before removal). */
   readonly routes: readonly CleanupRoute[]
 }
 
-/** Result of one dry-run planning pass. */
+/** Result of one planning pass; nothing has been deleted yet. */
 export interface CleanupPlan {
-  /** Retention window used for this plan, in milliseconds. */
+  /** Configured retention window in milliseconds. */
   readonly retentionMs: number
-  /** Activity cutoff (epoch ms); workspaces at or after it were kept. */
+  /** Epoch ms cutoff: activity older than this is stale. */
   readonly cutoff: number
-  /** Eligible workspaces, oldest activity first. */
+  /** Deletable candidates, oldest first. */
   readonly candidates: readonly CleanupCandidate[]
-  /** Plugin workspaces kept because a live session still uses them. */
+  /** Targets skipped because a Session using them is still live. */
   readonly skippedLive: number
 }
 
-/** One failed removal; the pass continues with the remaining candidates. */
+/** One failed removal (the run continues with the remaining candidates). */
 export interface CleanupFailure {
-  /** Workspace directory the failure belongs to. */
+  /** Directory that could not be removed. */
   readonly path: string
   /** Human-readable reason. */
   readonly message: string
 }
 
-/** Result of one apply pass. */
+/** Aggregate outcome of one apply pass. */
 export interface CleanupOutcome {
-  /** Workspaces whose directory was removed and registry record deleted. */
+  /** Legacy registered workspaces whose directory and record were removed. */
   readonly deletedWorkspaces: number
-  /** Active routes retired before their workspace was removed. */
+  /** Per-topic session directories removed. */
+  readonly deletedSessionDirs: number
+  /** Active routes retired into tombstones. */
   readonly retiredRoutes: number
-  /** Measured bytes of the deleted workspaces. */
+  /** Regular-file bytes reclaimed (measured before deletion). */
   readonly freedBytes: number
-  /** Per-workspace failures; other candidates were still processed. */
+  /** Per-candidate failures; a failing candidate does not abort the run. */
   readonly failures: readonly CleanupFailure[]
 }
 
-/** Whether a host workspace title marks the workspace as plugin-created. */
-function pluginWorkspaceTitle(title: string): boolean {
-  return PLUGIN_TITLE_PREFIXES.some(prefix => title.startsWith(prefix))
-}
+// ---- planning -----------------------------------------------------------
 
-/** Lexical path equality (both sides resolved the same way as `isPathInside`). */
+/** Lexically compare two paths (both resolved) without touching the disk. */
 function samePath(left: string, right: string): boolean {
   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: string): boolean {
+  const resolved = path.resolve(target)
+  return path.parse(resolved).root === resolved
+}
+
+/** Newest value of a list, or `undefined` when empty. */
 function newestActivity(values: readonly number[]): number | undefined {
-  let newest: number | undefined
-  for (const value of values) {
-    if (!Number.isFinite(value)) continue
-    if (newest === undefined || value > newest) newest = value
-  }
-  return newest
+  return values.length === 0 ? undefined : Math.max(...values)
 }
 
-/** Count/byte values never go negative or non-finite on the outcome path. */
 function nonNegative(value: number): number {
   return Number.isFinite(value) && value > 0 ? value : 0
 }
 
-/** Best-effort error text (never a stack trace). */
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
-}
-
-/** A filesystem root must never become the cleanup base directory. */
-function isFilesystemRoot(dir: string): boolean {
-  return path.parse(dir).root === dir
+async function readWorkspaceStats(
+  deps: CleanupDeps,
+  directory: string,
+): Promise<WorkspaceStats | undefined> {
+  try {
+    return await deps.statWorkspace(directory)
+  } catch (error) {
+    deps.warn?.(`dsh-channels: cleanup stats unavailable for ${directory}: ${String(error)}`)
+    return undefined
+  }
 }
 
-/** Liveness probe that fails safe: an unknowable session counts as live. */
 function sessionIsLive(deps: CleanupDeps, sessionId: string): boolean {
   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: CleanupDeps,
-  workspacePath: string,
-): Promise<WorkspaceStats | undefined> {
-  try {
-    return await deps.statWorkspace(workspacePath)
-  } catch (error) {
-    deps.warn?.(`dsh-channels: workspace stats unavailable for ${workspacePath}: ${errorMessage(error)}`)
-    return undefined
-  }
+function routesAreLive(deps: CleanupDeps, routes: readonly CleanupRoute[]): boolean {
+  return routes.some(route => sessionIsLive(deps, route.sessionId))
+}
+
+/** Effective directory of one route (workspace path on legacy routes). */
+function directoryOfRoute(route: CleanupRoute): string {
+  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
@@ -292,47 +326,64 @@ export async function planWorkspaceCleanup(deps: CleanupDeps): Promise<CleanupPl
 
   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 undefined
   }
+  const legacyRoot = legacyTopicWorkspaceRoot(baseDir)
 
   const now = deps.now?.() ?? Date.now()
   const cutoff = now - window
   const activeRoutes = await deps.activeRoutes()
   const tombstones = await deps.tombstones()
+  const workspaces = await deps.listWorkspaces()
   const candidates: CleanupCandidate[] = []
   let skippedLive = 0
 
-  for (const workspace of await deps.listWorkspaces()) {
+  // Paths of workspaces that are durable user projects (never deletable).
+  const userWorkspacePaths = new Set<string>()
+  for (const workspace of workspaces) {
+    const resolved = path.resolve(workspace.path)
     if (!pluginWorkspaceTitle(workspace.title)) continue
-    if (!isPathInside(baseDir, workspace.path)) continue
+    if (!isPathInside(baseDir, resolved)) continue
+    if (isPathInside(legacyRoot, resolved)) continue
+    userWorkspacePaths.add(resolved)
+  }
 
-    const routes = activeRoutes.filter(route => samePath(route.workspacePath, workspace.path))
-    if (routes.some(route => sessionIsLive(deps, route.sessionId))) {
+  // 1) Legacy one-workspace-per-topic directories.
+  for (const workspace of workspaces) {
+    if (!pluginWorkspaceTitle(workspace.title)) continue
+    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 === undefined || samePath(route.sessionDir, targetPath)))
+    if (routesAreLive(deps, routes)) {
       skippedLive++
       continue
     }
-
     let stats: WorkspaceStats | undefined
     let activityAt = newestActivity(routes.map(route => route.lastActivityAt))
     if (activityAt === undefined) {
       activityAt = newestActivity(
         tombstones
           .filter(tombstone => tombstone.workspacePath !== undefined
-            && samePath(tombstone.workspacePath, workspace.path))
+            && samePath(tombstone.workspacePath, targetPath)
+            && (tombstone.sessionDir === undefined || samePath(tombstone.sessionDir, targetPath)))
           .map(tombstone => tombstone.lastActivityAt ?? tombstone.expiredAt),
       )
     }
     if (activityAt === undefined) {
       // Orphan workspace: the directory's own mtime is the only age evidence.
-      stats = await readWorkspaceStats(deps, workspace.path)
+      stats = await readWorkspaceStats(deps, targetPath)
       activityAt = stats !== undefined && Number.isFinite(stats.mtimeMs) ? stats.mtimeMs : undefined
     }
     if (activityAt === undefined || 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 === undefined ? 0 : nonNegative(stats.bytes),
       files: stats === undefined ? 0 : nonNegative(stats.files),
@@ -340,25 +391,93 @@ export async function planWorkspaceCleanup(deps: CleanupDeps): Promise<CleanupPl
     })
   }
 
+  // 2) Per-topic session directories of the current layout: union of route
+  //    records, tombstones, and directories discovered on disk.
+  interface DirEvidence {
+    routes: CleanupRoute[]
+    tombstoneActivity: number[]
+    mtimeMs?: number
+  }
+  const dirs = new Map<string, DirEvidence>()
+  const evidenceFor = (directory: string): DirEvidence => {
+    const key = path.resolve(directory)
+    let evidence = dirs.get(key)
+    if (evidence === undefined) {
+      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: string): boolean => {
+    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 === undefined || 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 === undefined) continue
+    if (tombstone.workspacePath !== undefined && 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 === undefined || activityAt >= cutoff) continue
+    const stats = await readWorkspaceStats(deps, directory)
+    // Nothing left on disk and no active route to retire: nothing to do.
+    if (stats === undefined && evidence.routes.length === 0) continue
+    candidates.push({
+      target: { kind: 'session-dir', path: directory },
+      path: directory,
+      activityAt,
+      bytes: stats === undefined ? 0 : nonNegative(stats.bytes),
+      files: stats === undefined ? 0 : nonNegative(stats.files),
+      routes: evidence.routes,
+    })
+  }
+
   candidates.sort((left, right) =>
-    left.activityAt - right.activityAt || left.workspace.path.localeCompare(right.workspace.path))
+    left.activityAt - right.activityAt || left.path.localeCompare(right.path))
   return { retentionMs: window, cutoff, candidates, skippedLive }
 }
 
+// ---- application --------------------------------------------------------
+
 /**
- * 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.
  */
 export async function applyWorkspaceCleanup(
   deps: CleanupDeps,
@@ -366,33 +485,51 @@ export async function applyWorkspaceCleanup(
 ): Promise<CleanupOutcome> {
   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: CleanupFailure[] = []
   let deletedWorkspaces = 0
+  let deletedSessionDirs = 0
   let retiredRoutes = 0
   let freedBytes = 0
 
   for (const candidate of plan.candidates) {
-    const target = candidate.workspace.path
+    const target = candidate.target
+    const targetPath = candidate.path
     // Defense in depth: never trust a plan object for the destructive step.
-    if (baseDirIsRoot || !isPathInside(baseDir, target)) {
-      failures.push({ path: target, message: 'refused: workspace path is outside the cleanup base directory' })
+    const insideBase = !baseDirIsRoot && isPathInside(baseDir, targetPath)
+    const inLegacyRoot = isPathInside(legacyRoot, targetPath)
+    const valid = target.kind === 'workspace'
+      ? insideBase && inLegacyRoot
+      : insideBase && !inLegacyRoot && !registered.has(path.resolve(targetPath))
+    if (!valid) {
+      failures.push({ 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)
-      failures.push({ path: target, message })
-      deps.warn?.(`dsh-channels: workspace cleanup failed for ${target}: ${message}`)
+      const message = error instanceof Error ? error.message : String(error)
+      failures.push({ path: targetPath, message })
+      deps.warn?.(`dsh-channels: cleanup failed for ${targetPath}: ${message}`)
     }
   }
 
-  return { deletedWorkspaces, retiredRoutes, freedBytes, failures }
+  return { deletedWorkspaces, deletedSessionDirs, retiredRoutes, freedBytes, failures }
 }

package/src/client/api.ts

@@ -15,6 +15,7 @@ import {
   CONFIG_ROUTE,
   CREDENTIALS_ROUTE,
   PANEL_ROUTE,
+  PICK_DIRECTORY_ROUTE,
   RECONNECT_ROUTE,
   STATUS_ROUTE,
 } from '../settings/contract.ts'
@@ -29,6 +30,7 @@ import type {
   CredentialField,
   EditableValues,
   PanelWire,
+  PickDirectoryResponse,
   ReconnectResponse,
   SaveConfigResponse,
   SaveCredentialsRequest,
@@ -159,6 +161,24 @@ export async function runCleanup(): Promise<CleanupResponse> {
   return JSON.parse(text) as CleanupResponse
 }
 
+/**
+ * Ask the Host to open its native directory chooser (the panel's「选择目录…」
+ * button). The request stays open while the OS dialog does; a cancel comes back
+ * as `{ ok: true, canceled: true }`, not as an error.
+ */
+export async function pickDirectory(): Promise<PickDirectoryResponse> {
+  const response = await request(PICK_DIRECTORY_ROUTE, { method: 'POST' })
+  const text = await response.text()
+  if (!response.ok) {
+    try {
+      return JSON.parse(text) as PickDirectoryResponse
+    } catch {
+      return { ok: false, error: errorFromBody(response.status, text) }
+    }
+  }
+  return JSON.parse(text) as PickDirectoryResponse
+}
+
 /** Store provided credential values (the request/response never carry stored values). */
 export async function saveCredentials(values: SaveCredentialsRequest): Promise<SaveCredentialsResponse> {
   const response = await request(CREDENTIALS_ROUTE, {

package/src/client/catalog.ts

@@ -2,7 +2,7 @@
  * 浏览器半区的设置面板选择器目录折叠：把 Host 下发的字段描述与实时目录
  * （`/dsh-channels/catalog`）合成通用表单需要的 select 描述。
  *
- * 拆成独立模块（不含 JSX/React）以便单测；`panel.tsx` 只负责串起状态与渲染。
+ * 拆成独立模块（不含 JSX/React）以便单测；`panel/index.tsx` 只负责串起状态与渲染。
  *
  * @module dsh-channels/client/catalog
  */