dsh-managed-workspaces 1.0.0 → 1.1.0

package/README.md

@@ -18,24 +18,31 @@
 
 ## 安装
 
-从 GitHub 安装（推荐）：在 DSH 中让代理使用 `plugin_manager` 的 `install_bundle`：
+### 用 DSH 插件命令（推荐）
+
+已发布到 npm：<https://www.npmjs.com/package/dsh-managed-workspaces>
 
 ```
-plugin_manager({ action: "install_bundle", target: "https://github.com/CoraxEldridge/dsh-managed-workspaces" })
+dsh plugin --profile desktop add dsh-managed-workspaces
 ```
 
-也可以先把仓库克隆到本地，再用本地目录安装：
+把 `desktop` 换成你的 profile 名。该命令会在 profile 里安装包，并把新增的 bundle 自动加入 `dsh.profile.bundles`；重启 DSH 后生效。
+
+### 用 plugin_manager
 
 ```
-plugin_manager({ action: "install_bundle", target: "D:\\path\\to\\dsh-managed-workspaces" })
+plugin_manager({ action: "install_bundle", target: "dsh-managed-workspaces" })
 ```
 
-安装后侧边栏底部出现「托管工作区」入口；若结果显示 `restart-required`，重启 DSH 后生效。更新已安装版本：
+也可以从 GitHub 安装，或先用本地目录安装便于开发：
 
 ```
 plugin_manager({ action: "install_bundle", target: "https://github.com/CoraxEldridge/dsh-managed-workspaces" })
+plugin_manager({ action: "install_bundle", target: "D:\\path\\to\\dsh-managed-workspaces" })
 ```
 
+安装后侧边栏底部出现「托管工作区」入口；若结果显示 `restart-required`，重启 DSH 后生效。更新已安装版本时重复对应的安装命令即可。
+
 ## 接入已有工作区
 
 侧边栏里已经存在的工作区可以「接入」插件，纳入同一套管理（这样就能给它们关联额外文件夹），而且**不移动、不改名、不新建任何文件**：
@@ -49,6 +56,21 @@ plugin_manager({ action: "install_bundle", target: "https://github.com/CoraxEldr
 - 「移出插件」对**接入**的工作区只删除插件记录，保留它在侧边栏的注册（因为那个工作区原本就属于你）；对 **DSH 新建**的工作区则同时移除侧边栏注册。
 - 如果接入的工作区目录被外部删除，「修复」不会替你重建，只报告缺失。
 
+## 迁移工作区
+
+展开任一工作区，点「迁移…」，填入一个**尚不存在**的目标路径（或用「浏览…」选父目录后自动补上当前名称），确认即可。也可以用工具：`managed_workspace({ action: "migrate", destination: "D:\\新位置", workspace: "名称" })`。
+
+迁移会移动整个工作区目录（同一磁盘用重命名，跨磁盘用“复制 → 校验文件数/字节数 → 删除源”），并重建 `_roots` 下的关联链接。
+
+**对话记录为什么不会丢**：DSH 的会话头里记录着创建时的工作目录，且该记录不可修改；侧边栏按这个路径把会话归到工作区。因此：
+
+- 工作区**还有会话**时（自动 `anchor` 模式）：目录被移走，但**原路径会保留为指向新位置的目录链接**，历史会话的 cwd 仍然有效，对话照常打开、继续、归组在同一个工作区下。
+- 工作区**没有会话**时（自动 `clean` 模式）：直接移动并在侧边栏把工作区重新注册到新路径，不留链接。
+
+`anchor` 模式需要保留原位置的那一个链接；如果原磁盘将被移除，请先确认该路径可以长期保留（链接本身只占极小空间）。手动指定 `mode: "clean"` 时，若工作区仍有会话会被拒绝。
+
+迁移后界面会显示「实际位置」。若链接被误删，点「修复」即可重建。
+
 ## 使用
 
 1. 打开侧边栏底部的「托管工作区」，设置**工作区根目录**并保存。
@@ -80,6 +102,7 @@ plugin_manager({ action: "install_bundle", target: "https://github.com/CoraxEldr
 - **搜索不会自动穿越链接**：`glob`/`grep` 通过 ripgrep 执行且不带 `--follow`，所以从工作区根搜索一般不会进入 `_roots/<别名>`。请对每个关联文件夹显式指定路径，例如 `grep({ path: "_roots/web" })`。插件会在提示上下文中提醒模型。
 - **`workspace-write` 下无法写关联文件夹**：链接目标是工作区根之外的路径，文件沙箱会拒绝写入（Windows 上又无法用 `additionalWritableRoots` 表达，因为会让 pwsh 的 ACL 沙箱直接失败）。需要修改关联文件夹时把会话切到 `danger-full-access`。
 - **不支持 UNC 路径**：Windows junction 不能指向网络共享（会明确报错）。
+- **会话不能跨工作区拖动或移动**：工作区归属由会话头中不可变的 `cwd` 推导（`attachSession` 要求它等于工作区路径），DSH 没有修改该记录的接口。侧边栏的拖拽只在同一工作区内排序；要整理对话位置，请用本插件的「迁移工作区」移动目录。
 - 工作区文件夹被外部删除时不会静默重建，需在界面点「修复」。
 - 若 `_roots/<别名>` 被真实文件或目录占用，插件只报告冲突，绝不覆盖或删除。
 - 卸载插件不会动磁盘上的任何工作区文件夹、链接或会话。

package/client.js

@@ -42,6 +42,16 @@ window.__ModuleLoader__.load({
       'health.conflict': '冲突',
       register: '注册到侧边栏',
       repair: '修复',
+      migrate: '迁移…',
+      migrateCancel: '取消',
+      migrateStart: '开始迁移',
+      migrateTitle: '迁移到新位置',
+      migrateDestination: '目标路径（必须尚不存在）',
+      migrateHint: '会移动工作区目录；普通文件不受影响。',
+      migrateAnchorHint: '该工作区有 {count} 个会话。迁移后原路径会保留为指向新位置的目录链接，历史对话继续可用（会话记录里的工作目录不可修改）。',
+      migrateCleanHint: '该工作区没有会话，将直接迁移并在侧边栏更新为新路径。',
+      migrateConfirm: '现在迁移工作区「{name}」？\n\n{detail}\n\n目标：{destination}',
+      migratedTo: '实际位置',
       forget: '从插件移除',
       forgetConfirm: '从插件移除工作区「{name}」？\n只会删除侧边栏注册与插件记录，不会删除任何文件夹或会话。',
       forgetAdopted: '移出插件',
@@ -85,6 +95,16 @@ window.__ModuleLoader__.load({
       'health.conflict': 'Conflict',
       register: 'Register in sidebar',
       repair: 'Repair',
+      migrate: 'Migrate…',
+      migrateCancel: 'Cancel',
+      migrateStart: 'Migrate',
+      migrateTitle: 'Migrate to a new location',
+      migrateDestination: 'Destination path (must not exist yet)',
+      migrateHint: 'Moves the workspace directory; ordinary files are unaffected.',
+      migrateAnchorHint: 'This workspace has {count} session(s). After migrating, the original path stays as a directory link to the new location so the recorded conversations keep working (a session records its working directory immutably).',
+      migrateCleanHint: 'No session uses this workspace, so it is moved and re-registered at the new path directly.',
+      migrateConfirm: 'Migrate workspace "{name}" now?\n\n{detail}\n\nDestination: {destination}',
+      migratedTo: 'Content location',
       forget: 'Remove from plugin',
       forgetConfirm: 'Remove workspace "{name}" from the plugin?\nOnly the sidebar registration and the plugin record are removed; no folder or session is deleted.',
       forgetAdopted: 'Stop managing',
@@ -143,6 +163,7 @@ window.__ModuleLoader__.load({
 .dsh-mws-code{font-family:var(--dsw-font-family);font-size:12px;color:var(--dsw-alias-label-secondary);}
 .dsh-mws-arrow{color:var(--dsw-alias-label-tertiary);}
 .dsh-mws-addlink{display:flex;flex-direction:column;gap:6px;padding:8px;border:1px dashed var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-sm);}
+.dsh-mws-migrate{display:flex;flex-direction:column;gap:8px;padding:10px;border:1px dashed var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-sm);background:var(--dsw-alias-bg-layer-1);}
 .dsh-mws-candidate{display:flex;align-items:center;gap:8px;padding:8px 10px;border:1px solid var(--dsw-alias-border-l1);border-radius:var(--dsw-radius-sm);background:var(--dsw-alias-bg-layer-1);}
 @media (max-width:520px){.dsh-mws-backdrop{padding:0;}.dsh-mws-dialog{max-height:100vh;height:100vh;border-radius:0;}}
 `
@@ -516,6 +537,7 @@ window.__ModuleLoader__.load({
         const ws = props.ws
         const busy = props.busy
         const [expanded, setExpanded] = React.useState(false)
+        const [migrating, setMigrating] = React.useState(false)
         const statusKey =
           ws.directory !== 'ok'
             ? 'status.missing'
@@ -551,10 +573,26 @@ window.__ModuleLoader__.load({
                 h('span', { className: 'dsh-mws-chip ' + tone }, t(statusKey)),
               ),
               h('div', { className: 'dsh-mws-path', title: ws.path }, ws.path),
+              ws.relocatedTo !== null && ws.relocatedTo !== undefined
+                ? h('div', { className: 'dsh-mws-hint' }, t('migratedTo') + ': ' + ws.relocatedTo)
+                : null,
             ),
             h(
               'div',
               { className: 'dsh-mws-actions' },
+              h(
+                'button',
+                {
+                  type: 'button',
+                  className: 'dsh-mws-btn',
+                  disabled: busy !== null || ws.directory !== 'ok',
+                  onClick: () => {
+                    setExpanded(true)
+                    setMigrating(true)
+                  },
+                },
+                t('migrate'),
+              ),
               !ws.registered
                 ? h(
                     'button',
@@ -597,6 +635,7 @@ window.__ModuleLoader__.load({
             ? h(
                 'div',
                 { className: 'dsh-mws-card-body' },
+                migrating ? h(MigrateForm, { t, ws, busy, onClose: () => setMigrating(false) }) : null,
                 h('div', { className: 'dsh-mws-label' }, t('linksLabel')),
                 ws.links.length === 0
                   ? h('div', { className: 'dsh-mws-hint' }, t('linksEmpty'))
@@ -608,6 +647,77 @@ window.__ModuleLoader__.load({
         )
       }
 
+      function MigrateForm(props) {
+        const t = props.t
+        const ws = props.ws
+        const busy = props.busy
+        const [destination, setDestination] = React.useState('')
+        const detail =
+          ws.sessionCount > 0
+            ? t('migrateAnchorHint').replace('{count}', String(ws.sessionCount))
+            : t('migrateCleanHint')
+        const submit = async () => {
+          const value = destination.trim()
+          if (value === '') return
+          const confirmed = window
+            .confirm(t('migrateConfirm').replace('{name}', ws.name).replace('{detail}', detail).replace('{destination}', value))
+          if (!confirmed) return
+          const ok = await mutate('migrate', { id: ws.id, destination: value, mode: 'auto' })
+          if (ok) {
+            setDestination('')
+            props.onClose()
+          }
+        }
+        const browse = async () => {
+          const picked = await pickFolder()
+          if (picked === null) return
+          const name = ws.path.split(/[\\/]/).filter(Boolean).pop() ?? 'workspace'
+          const separator = picked.includes('\\') ? '\\' : '/'
+          setDestination(picked.replace(/[\\/]+$/, '') + separator + name)
+        }
+        return h(
+          'div',
+          { className: 'dsh-mws-migrate' },
+          h('div', { className: 'dsh-mws-label' }, t('migrateTitle')),
+          h(
+            'div',
+            { className: 'dsh-mws-row' },
+            h('input', {
+              className: 'dsh-mws-input dsh-mws-grow',
+              value: destination,
+              placeholder: t('migrateDestination'),
+              spellCheck: false,
+              onChange: (event) => setDestination(event.target.value),
+              onKeyDown: (event) => {
+                if (event.key === 'Enter') submit()
+              },
+            }),
+            h('button', { type: 'button', className: 'dsh-mws-btn', onClick: browse }, t('browse')),
+          ),
+          h('div', { className: 'dsh-mws-hint' }, detail),
+          h('div', { className: 'dsh-mws-hint' }, t('migrateHint')),
+          h(
+            'div',
+            { className: 'dsh-mws-row' },
+            h(
+              'button',
+              { type: 'button', className: 'dsh-mws-btn', disabled: busy !== null, onClick: () => props.onClose() },
+              t('migrateCancel'),
+            ),
+            h(
+              'button',
+              {
+                type: 'button',
+                className: 'dsh-mws-btn dsh-mws-primary',
+                disabled: busy !== null || destination.trim() === '',
+                onClick: submit,
+              },
+              t('migrateStart'),
+            ),
+          ),
+        )
+      }
+
       function LinkRow(props) {
         const t = props.t
         const ws = props.ws

package/context.js

@@ -16,6 +16,9 @@ export function renderContext(workspace, linksDirectoryName) {
     `Managed workspace "${workspace.name}"`,
     `Root: "${workspace.path}"`,
   ]
+  if (typeof workspace.relocatedTo === 'string' && workspace.relocatedTo !== workspace.path) {
+    lines.push(`Content location: "${workspace.relocatedTo}" (Root is a link to it; use Root for every path).`)
+  }
   if (links.length === 0) {
     lines.push('Linked folders: none.')
   } else {
@@ -68,6 +71,9 @@ export function registerManagedWorkspaceContext(ctx, store) {
         {
           name: found.workspace.name,
           path: found.workspace.path,
+          ...(typeof found.workspace.relocatedTo === 'string'
+            ? { relocatedTo: found.workspace.relocatedTo }
+            : {}),
           links: found.workspace.links.map((link) => ({ alias: link.alias, target: link.target })),
         },
         linksDirectoryName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-managed-workspaces",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "DSH-owned workspaces created under a configurable base directory, with multiple linked folders per workspace.",
   "keywords": [

package/routes.js

@@ -100,6 +100,7 @@ export function registerRoutes(ctx, store) {
   route('config', async (args) => store.setBaseDirectory(args.baseDirectory))
   route('create', async (args) => store.create(args.name))
   route('adopt', async (args) => (args.all === true ? store.adoptAll() : store.adopt(args.folder)))
+  route('migrate', async (args) => store.migrate(args.id, args.destination, { mode: args.mode }))
   route('attach', async (args) => store.attach(args.id, args.folder, args.alias))
   route('detach', async (args) => store.detach(args.id, args.alias))
   route('register', async (args) => store.register(args.id))

package/store.js

@@ -10,7 +10,7 @@
 
 import { execFile } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
-import { lstat, mkdir, readFile, readlink, realpath, rename, stat, symlink, unlink, writeFile } from 'node:fs/promises'
+import { cp, lstat, mkdir, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, unlink, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, basename, parse, resolve, sep } from 'node:path'
 import { promisify } from 'node:util'
@@ -161,6 +161,95 @@ async function createDirectoryLink(target, linkPath) {
   await symlink(target, linkPath, 'dir')
 }
 
+/** Remove one directory link, refusing to touch a real directory or a link to another target. */
+async function detachLinkNode(linkPath, expectedTarget) {
+  const node = await lstatOrNull(linkPath)
+  if (node === null) return 'missing'
+  if (!node.isSymbolicLink()) fail('conflict', `refusing to remove "${linkPath}": it is a real directory or file, not a link`)
+  const actual = await resolveLink(linkPath)
+  if (!samePath(actual, expectedTarget)) {
+    fail('conflict', `refusing to remove "${linkPath}": it points to ${actual}, not ${expectedTarget}`)
+  }
+  await unlink(linkPath)
+  return 'removed'
+}
+
+/** Ensure a directory link exists at `linkPath`, adopting an equivalent one and refusing conflicts. */
+async function ensureLinkNode(linkPath, target) {
+  const node = await lstatOrNull(linkPath)
+  if (node === null) {
+    await createDirectoryLink(target, linkPath)
+    return
+  }
+  if (!node.isSymbolicLink()) fail('conflict', `path already exists and is not a link: ${linkPath}`)
+  const actual = await resolveLink(linkPath)
+  if (!samePath(actual, target)) fail('conflict', `link points to ${actual}, not ${target}`)
+}
+
+/** Count files, directories, links, and bytes below one directory for copy verification. */
+async function treeSummary(root) {
+  let files = 0
+  let directories = 0
+  let symlinks = 0
+  let bytes = 0
+  const stack = [root]
+  while (stack.length > 0) {
+    const directory = stack.pop()
+    const entries = await readdir(directory, { withFileTypes: true })
+    for (const entry of entries) {
+      const full = join(directory, entry.name)
+      if (entry.isSymbolicLink()) {
+        symlinks += 1
+      } else if (entry.isDirectory()) {
+        directories += 1
+        stack.push(full)
+      } else {
+        files += 1
+        bytes += (await stat(full)).size
+      }
+    }
+  }
+  return { files, directories, symlinks, bytes }
+}
+
+/**
+ * Move a directory: rename when both paths share a volume, otherwise copy,
+ * verify the copy against the source, and only then remove the source.
+ * @param {string} source - existing directory.
+ * @param {string} destination - path that must not exist yet.
+ * @returns {Promise<'rename' | 'copy'>} which mechanism moved the tree.
+ */
+async function moveDirectory(source, destination) {
+  try {
+    await rename(source, destination)
+    return 'rename'
+  } catch (error) {
+    if (error.code !== 'EXDEV') throw error
+  }
+  await cp(source, destination, {
+    recursive: true,
+    errorOnExist: true,
+    force: false,
+    preserveTimestamps: true,
+  })
+  const left = await treeSummary(source)
+  const right = await treeSummary(destination)
+  const matches =
+    left.files === right.files &&
+    left.directories === right.directories &&
+    left.symlinks === right.symlinks &&
+    left.bytes === right.bytes
+  if (!matches) {
+    await rm(destination, { recursive: true, force: true })
+    fail(
+      'copy-mismatch',
+      `copied tree does not match the source (${JSON.stringify(left)} vs ${JSON.stringify(right)}); the source was kept`,
+    )
+  }
+  await rm(source, { recursive: true, force: true })
+  return 'copy'
+}
+
 function freshManifest() {
   return {
     schemaVersion: MANIFEST_VERSION,
@@ -212,6 +301,9 @@ function normalizeManifest(raw, warnings) {
         id: entry.id,
         name: entry.name,
         path: normalizePath(entry.path),
+        ...(typeof entry.relocatedTo === 'string' && isAbsolute(entry.relocatedTo)
+          ? { relocatedTo: normalizePath(entry.relocatedTo) }
+          : {}),
         createdAt: typeof entry.createdAt === 'string' ? entry.createdAt : new Date(0).toISOString(),
         origin: entry.origin === 'adopted' ? 'adopted' : 'created',
         links,
@@ -325,11 +417,37 @@ export class ManagedWorkspaceStore {
     return join(record.path, this.requireManifest().linksDirectoryName ?? LINKS_DIRECTORY)
   }
 
+  linksDirectoryAt(base) {
+    return join(base, this.requireManifest().linksDirectoryName ?? LINKS_DIRECTORY)
+  }
+
+  /** The registered workspace entity for a record (anchor or migrated location), or null. */
+  registryEntity(record) {
+    if (this.registry === null) return null
+    const match = this.registry.list().find(
+      (workspace) =>
+        samePath(workspace.path, record.path) ||
+        (typeof record.relocatedTo === 'string' && samePath(workspace.path, record.relocatedTo)),
+    )
+    return match ?? null
+  }
+
   /** The registered workspace id for a record, or null. */
   registryWorkspaceId(record) {
-    if (this.registry === null) return null
-    const match = this.registry.list().find((workspace) => samePath(workspace.path, record.path))
-    return match === undefined ? null : String(match.id)
+    const entity = this.registryEntity(record)
+    return entity === null ? null : String(entity.id)
+  }
+
+  /** How many sessions the registry accounts to this workspace. */
+  sessionCountOf(record) {
+    const entity = this.registryEntity(record)
+    const ids = entity?.sessionIds
+    return Array.isArray(ids) ? ids.length : 0
+  }
+
+  /** The physical directory holding the workspace content (anchor resolved). */
+  async realPathOf(record) {
+    return normalizePath(await realpath(record.path))
   }
 
   /** All managed workspace records (loaded state only). */
@@ -371,6 +489,13 @@ export class ManagedWorkspaceStore {
       if (typeof workspace.path !== 'string') continue
       if (this.isFilesystemRoot(workspace.path)) continue
       if (this.manifest.workspaces.some((record) => samePath(record.path, workspace.path))) continue
+      if (
+        this.manifest.workspaces.some(
+          (record) => typeof record.relocatedTo === 'string' && samePath(record.relocatedTo, workspace.path),
+        )
+      ) {
+        continue
+      }
       const title = typeof workspace.title === 'string' && workspace.title.trim().length > 0 ? workspace.title.trim() : basename(workspace.path)
       out.push({ path: normalizePath(workspace.path), title, workspaceId: String(workspace.id) })
     }
@@ -382,6 +507,9 @@ export class ManagedWorkspaceStore {
     if (this.manifest === null || typeof path !== 'string') return null
     for (const workspace of this.manifest.workspaces) {
       if (isUnder(path, workspace.path)) return { workspace, via: 'home' }
+      if (typeof workspace.relocatedTo === 'string' && isUnder(path, workspace.relocatedTo)) {
+        return { workspace, via: 'relocated' }
+      }
     }
     for (const workspace of this.manifest.workspaces) {
       for (const link of workspace.links) {
@@ -415,11 +543,13 @@ export class ManagedWorkspaceStore {
       id: record.id,
       name: record.name,
       path: record.path,
+      relocatedTo: typeof record.relocatedTo === 'string' ? record.relocatedTo : null,
       createdAt: record.createdAt,
       origin: record.origin === 'adopted' ? 'adopted' : 'created',
       directory: (await isDirectory(record.path)) ? 'ok' : 'missing',
       registered: workspaceId !== null,
       workspaceId,
+      sessionCount: this.sessionCountOf(record),
       links,
     }
   }
@@ -552,6 +682,12 @@ export class ManagedWorkspaceStore {
     if (existing !== undefined) {
       return { workspace: await this.view(existing), adopted: false }
     }
+    const relocated = this.requireManifest().workspaces.find(
+      (record) => typeof record.relocatedTo === 'string' && samePath(record.relocatedTo, target),
+    )
+    if (relocated !== undefined) {
+      fail('already-managed', `this folder is already the migrated location of workspace "${relocated.name}"`)
+    }
     const preferred = this.registryTitle(target) ?? basename(target)
     const record = {
       id: `mws-${randomUUID()}`,
@@ -580,6 +716,193 @@ export class ManagedWorkspaceStore {
     }
   }
 
+  /** Recreate a set of recorded links under one base directory (best effort). */
+  async restoreLinks(links, base) {
+    const errors = []
+    if (links.length === 0) return errors
+    const roots = this.linksDirectoryAt(base)
+    await mkdir(roots, { recursive: true })
+    for (const link of links) {
+      try {
+        await ensureLinkNode(join(roots, link.alias), link.target)
+      } catch (error) {
+        errors.push(`${link.alias}: ${errorMessage(error)}`)
+      }
+    }
+    return errors
+  }
+
+  /** Remove every recorded link node below a base directory, returning the removed ones. */
+  async detachRecordLinks(record, base) {
+    const roots = this.linksDirectoryAt(base)
+    const detached = []
+    for (const link of record.links) {
+      const result = await detachLinkNode(join(roots, link.alias), link.target)
+      if (result === 'removed') detached.push(link)
+    }
+    return detached
+  }
+
+  /** Point the stable anchor path at the migrated directory, replacing a stale link. */
+  async ensureAnchorLink(record, destination, previous) {
+    const anchor = record.path
+    const node = await lstatOrNull(anchor)
+    if (node === null) {
+      await mkdir(dirname(anchor), { recursive: true })
+      await createDirectoryLink(destination, anchor)
+      return
+    }
+    if (!node.isSymbolicLink()) {
+      fail('conflict', `refusing to replace "${anchor}": it is a real directory or file`)
+    }
+    const actual = await resolveLink(anchor)
+    if (samePath(actual, destination)) return
+    if (!samePath(actual, previous) && !isUnder(actual, previous)) {
+      fail('conflict', `refusing to replace "${anchor}": it points to ${actual}`)
+    }
+    await unlink(anchor)
+    await createDirectoryLink(destination, anchor)
+  }
+
+  /**
+   * Move a workspace's directory to a new location.
+   *
+   * A session records its original working directory immutably, and the
+   * workspace registry groups sessions by that recorded path. Moving the
+   * folder would strand every conversation, so a workspace that still has
+   * sessions keeps its original path as a directory link to the new location
+   * (`anchor` mode). A workspace without sessions is re-registered at the new
+   * path instead (`clean` mode), leaving no link behind.
+   */
+  async migrate(id, destination, options = {}) {
+    await this.load()
+    return this.run(async () => {
+      const record = this.mustFind(id)
+      const raw = typeof destination === 'string' ? destination.trim() : ''
+      if (raw.length === 0) fail('invalid-target', 'destination must be a non-blank absolute path')
+      const expanded = expandHomePath(raw)
+      if (!isAbsolute(expanded)) fail('invalid-target', `destination must be absolute: ${JSON.stringify(destination)}`)
+      const target = normalizePath(expanded)
+      if (this.isFilesystemRoot(target)) fail('invalid-target', `a filesystem root cannot be a workspace: ${target}`)
+      if (samePath(target, this.requireManifest().baseDirectory)) {
+        fail('invalid-target', 'the workspace base directory cannot itself be a workspace')
+      }
+      if ((await lstatOrNull(target)) !== null) fail('exists', `destination already exists: ${target}`)
+
+      const source = await this.realPathOf(record)
+      if (samePath(target, source)) fail('invalid-target', 'destination is the current workspace location')
+      if (isUnder(target, source)) fail('invalid-target', 'cannot move a workspace into itself')
+      if (isUnder(source, target)) fail('invalid-target', 'cannot move a workspace onto its own parent')
+      for (const link of record.links) {
+        if (isUnder(target, link.target)) fail('invalid-target', 'cannot move a workspace into one of its linked folders')
+      }
+      if (this.registry !== null) {
+        const clash = this.registry
+          .list()
+          .find(
+            (workspace) =>
+              samePath(workspace.path, target) &&
+              !samePath(workspace.path, record.path) &&
+              !(typeof record.relocatedTo === 'string' && samePath(workspace.path, record.relocatedTo)),
+          )
+        if (clash !== undefined) fail('exists', `another registered workspace already uses ${target}`)
+      }
+      if (
+        this.listSync().some(
+          (other) =>
+            other.id !== record.id &&
+            (samePath(other.path, target) ||
+              (typeof other.relocatedTo === 'string' && samePath(other.relocatedTo, target))),
+        )
+      ) {
+        fail('exists', `another managed workspace already uses ${target}`)
+      }
+
+      const sessionCount = this.sessionCountOf(record)
+      const requested = options.mode === undefined ? 'auto' : String(options.mode)
+      if (!['auto', 'anchor', 'clean'].includes(requested)) fail('invalid-mode', `unknown migration mode: ${requested}`)
+      const mode = requested === 'auto' ? (sessionCount === 0 ? 'clean' : 'anchor') : requested
+      if (mode === 'clean' && sessionCount > 0) {
+        fail(
+          'sessions-present',
+          `this workspace still has ${sessionCount} session(s); a clean migration would detach them. Use the anchor mode instead.`,
+        )
+      }
+
+      let detached = []
+      try {
+        detached = await this.detachRecordLinks(record, source)
+      } catch (error) {
+        const errors = await this.restoreLinks(detached, source)
+        fail(
+          'conflict',
+          `cannot prepare links for the move: ${errorMessage(error)}${errors.length > 0 ? `; restoring them also failed: ${errors.join('; ')}` : ''}`,
+        )
+      }
+
+      let movedBy
+      try {
+        await mkdir(dirname(target), { recursive: true })
+        movedBy = await moveDirectory(source, target)
+      } catch (error) {
+        const errors = await this.restoreLinks(detached, source)
+        fail(
+          'move-failed',
+          `${errorMessage(error)}${errors.length > 0 ? `; restoring links also failed: ${errors.join('; ')}` : ''}`,
+        )
+      }
+
+      const linksDirName = this.requireManifest().linksDirectoryName ?? LINKS_DIRECTORY
+      const linkErrors = record.links.length > 0 ? await this.restoreLinks(record.links, target) : []
+      if (!(await isDirectory(join(target, linksDirName))) && record.origin !== 'adopted') {
+        await mkdir(join(target, linksDirName), { recursive: true })
+      }
+
+      if (mode === 'clean') {
+        try {
+          const entity = this.registryEntity(record)
+          if (entity !== null) await this.registry.delete(String(entity.id))
+          if (this.registry !== null) await this.registry.create(target, record.name)
+        } catch (error) {
+          record.relocatedTo = target
+          await this.persist()
+          fail(
+            'registration-failed',
+            `the directory moved to ${target}, but re-registering it failed: ${errorMessage(error)}. Run repair to re-anchor the original path.`,
+          )
+        }
+        record.path = target
+        delete record.relocatedTo
+        await this.persist()
+        return { workspace: await this.view(record), mode, source, destination: target, sessionCount, linkErrors, movedBy }
+      }
+
+      try {
+        await this.ensureAnchorLink(record, target, source)
+      } catch (anchorError) {
+        try {
+          await moveDirectory(target, source)
+          await this.restoreLinks(record.links, source)
+          if (typeof record.relocatedTo === 'string') await this.ensureAnchorLink(record, record.relocatedTo, source)
+        } catch (rollbackError) {
+          record.relocatedTo = target
+          await this.persist()
+          fail(
+            'migration-incomplete',
+            `moved to ${target}, but the original path ${record.path} is unusable (${errorMessage(anchorError)}) and rolling back failed (${errorMessage(rollbackError)}). Create a link from ${record.path} to ${target} manually, then run repair.`,
+          )
+        }
+        fail(
+          'migration-rollback',
+          `could not keep the original path usable (${errorMessage(anchorError)}); the directory was moved back to ${source}`,
+        )
+      }
+      record.relocatedTo = target
+      await this.persist()
+      return { workspace: await this.view(record), mode, source, destination: target, sessionCount, linkErrors, movedBy }
+    })
+  }
+
   async attach(id, folder, alias) {
     await this.load()
     return this.run(async () => {
@@ -694,14 +1017,33 @@ export class ManagedWorkspaceStore {
       const record = this.mustFind(id)
       const repaired = []
       const conflicts = []
-      if (!(await isDirectory(record.path))) {
+      const relocated = typeof record.relocatedTo === 'string' ? record.relocatedTo : null
+
+      if (relocated !== null) {
+        if (!(await isDirectory(relocated))) {
+          fail('missing', `the migrated workspace folder is missing and will not be recreated: ${relocated}`)
+        }
+        // The original path is the anchor every recorded session still uses.
+        try {
+          await this.ensureAnchorLink(record, relocated, relocated)
+          if (!(await isDirectory(record.path))) {
+            conflicts.push(`anchor ${record.path} does not resolve to ${relocated}`)
+          } else if (await samePath(await this.realPathOf(record), relocated)) {
+            if (repaired.length === 0) repaired.push('anchor')
+          }
+        } catch (error) {
+          conflicts.push(`anchor: ${errorMessage(error)}`)
+        }
+      } else if (!(await isDirectory(record.path))) {
         if (record.origin === 'adopted') {
           fail('missing', `the adopted workspace folder is missing and will not be recreated: ${record.path}`)
         }
         await mkdir(record.path, { recursive: true })
         repaired.push('workspace folder')
       }
-      const roots = this.linksDirectory(record)
+
+      const base = relocated ?? record.path
+      const roots = this.linksDirectoryAt(base)
       // A created workspace always owns its _roots; an adopted one gets it only
       // when a linked folder actually needs it, so adoption leaves no trace.
       if (!(await isDirectory(roots)) && (record.links.length > 0 || record.origin !== 'adopted')) {

package/tool.js

@@ -5,7 +5,7 @@
 
 import { ManagedWorkspaceError } from './store.js'
 
-const ACTIONS = ['status', 'list', 'create', 'adopt', 'attach', 'detach', 'register', 'forget']
+const ACTIONS = ['status', 'list', 'create', 'adopt', 'attach', 'detach', 'migrate', 'register', 'forget']
 
 const PARAMETERS = {
   type: 'object',
@@ -14,7 +14,7 @@ const PARAMETERS = {
     action: {
       type: 'string',
       enum: ACTIONS,
-      description: 'status reads the current session workspace; list reads every managed workspace and the existing workspaces that are not managed yet; create makes a new workspace folder; adopt registers an existing folder (or every existing sidebar workspace) without moving it; attach/detach add or remove one linked folder; register re-registers a workspace in the sidebar; forget removes the plugin record without deleting any folder.',
+      description: 'status reads the current session workspace; list reads every managed workspace and the existing workspaces that are not managed yet; create makes a new workspace folder; adopt registers an existing folder (or every existing sidebar workspace) without moving it; attach/detach add or remove one linked folder; migrate moves the workspace directory while keeping its conversations usable; register re-registers a workspace in the sidebar; forget removes the plugin record without deleting any folder.',
     },
     name: {
       type: 'string',
@@ -28,6 +28,15 @@ const PARAMETERS = {
       type: 'boolean',
       description: 'For action=adopt: adopt every sidebar workspace this plugin does not manage yet.',
     },
+    destination: {
+      type: 'string',
+      description: 'Absolute destination path for action=migrate. It must not exist yet; the workspace directory is moved there.',
+    },
+    mode: {
+      type: 'string',
+      enum: ['auto', 'anchor', 'clean'],
+      description: 'For action=migrate: auto keeps the original path as a link when the workspace still has sessions (required for conversations to keep working) and re-registers a session-less workspace at the new path; anchor always keeps the original path as a link; clean refuses a workspace that still has sessions.',
+    },
     alias: {
       type: 'string',
       description: 'Link name under the workspace _roots directory. Defaults to the folder name; ignored for detach when omitted.',
@@ -62,7 +71,13 @@ function linkLines(view) {
 }
 
 function workspaceBlock(view) {
-  return [`Workspace "${view.name}" at ${view.path} [${statusLabel(view)}]`, 'Linked folders:', ...linkLines(view)].join('\n')
+  const lines = [`Workspace "${view.name}" at ${view.path} [${statusLabel(view)}]`]
+  if (view.relocatedTo !== null && view.relocatedTo !== undefined) {
+    lines.push(`Content location: ${view.relocatedTo} (the original path is kept as a link so recorded sessions stay usable)`)
+  }
+  lines.push(`Sessions: ${view.sessionCount ?? 0}`)
+  lines.push('Linked folders:', ...linkLines(view))
+  return lines.join('\n')
 }
 
 function listBlock(state) {
@@ -198,6 +213,23 @@ export function createManagedWorkspaceTool(ctx, store) {
         return { summary: `${headline}\n${workspaceBlock(result.workspace)}${warning}` }
       }
 
+      if (action === 'migrate') {
+        const record = resolveTarget(args, exec)
+        if (typeof args.destination !== 'string' || args.destination.trim().length === 0) {
+          throw new ManagedWorkspaceError('invalid-target', 'action=migrate requires "destination"')
+        }
+        const result = await store.migrate(record.id, args.destination, { mode: args.mode })
+        const explanation =
+          result.mode === 'anchor'
+            ? `The original path is kept as a directory link to the new location, so the ${result.sessionCount} recorded session(s) and their conversations keep working.`
+            : 'The workspace had no sessions, so it was re-registered at the new path with no link left behind.'
+        const linkNote =
+          result.linkErrors.length === 0 ? '' : `\nLink warnings: ${result.linkErrors.join('; ')}`
+        return {
+          summary: `Moved the workspace content from ${result.source} to ${result.destination} (${result.movedBy}).\n${explanation}${linkNote}\n${workspaceBlock(result.workspace)}`,
+        }
+      }
+
       if (action === 'register') {
         const record = resolveTarget(args, exec)
         const result = await store.register(record.id)