clawt 3.10.5 → 3.10.6

package/docs/superpowers/specs/2026-06-09-worktree-base-branch-design.md

@@ -0,0 +1,169 @@
+# Worktree Base Branch Design
+
+## 背景
+
+当前 `clawt status`、`clawt status -i` 和 `clawt list` 会把同一项目下的 worktree 展示在一起，但不会标明这些 worktree 分支最初基于哪个分支创建。当用户同时从 `master`、`test` 等多个分支创建 worktree 时，容易把基于 `test` 的 worktree 误合并到 `master`，风险较高。
+
+## 目标
+
+- 在 `clawt create` 创建 worktree 时记录创建瞬间的真实当前分支，作为该 worktree 的来源分支。
+- 在 `clawt status`、`clawt status -i`、`clawt list` 中展示来源分支。
+- JSON 输出包含稳定字段，便于脚本消费。
+- 历史 worktree 没有元数据时明确展示未记录，不通过不可靠 git 推断伪造结果。
+
+## 非目标
+
+- 不新增历史回填命令。
+- 不修改 `clawt merge` 的合并目标逻辑。
+- 不改变 `clawt init` 的项目主工作分支配置语义。
+- 不把 worktree 元数据写入 `~/.clawt/projects/<projectName>/config.json`。
+
+## 来源分支语义
+
+来源分支定义为执行 `clawt create` 时，创建 worktree 前主 worktree 当前所在的真实分支。示例：用户当时位于 `test` 分支并创建 `feature-login`，则 `feature-login` 的 `baseBranch` 为 `test`。
+
+该语义优先于项目配置中的 `clawtMainWorkBranch`。如果现有前置检查在创建前切换了分支，则记录切换后的真实当前分支，因为它才是实际执行 `git worktree add -b` 的基准。
+
+## 存储设计
+
+每个 worktree 分支使用一个独立 JSON 文件：
+
+```text
+~/.clawt/projects/<projectName>/worktrees/<branchName>.json
+```
+
+文件内容：
+
+```json
+{
+  "branch": "feature-login",
+  "baseBranch": "test",
+  "createdAt": "2026-06-09T10:30:00.000Z"
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `branch` | `string` | worktree 对应分支名 |
+| `baseBranch` | `string` | 创建 worktree 时所在的真实当前分支 |
+| `createdAt` | `string` | 元数据写入时间，ISO 8601 字符串 |
+
+元数据属于项目级动态数据，应放在 `~/.clawt/projects/<projectName>/worktrees/` 下。项目配置 `config.json` 继续只保存配置项，避免运行元数据污染配置文件。
+
+## 代码结构
+
+新增 `src/utils/worktree-metadata.ts`，职责限定为 worktree 元数据路径、读写、删除：
+
+- `getWorktreeMetadataPath(projectName, branchName)`：生成单个分支元数据路径。
+- `saveWorktreeMetadata(projectName, metadata)`：保存来源分支元数据。
+- `loadWorktreeMetadata(projectName, branchName)`：读取元数据，缺失或解析失败时返回 `null`。
+- `removeWorktreeMetadata(projectName, branchName)`：删除元数据，文件不存在时不报错。
+
+新增类型 `WorktreeMetadata`，包含 `branch`、`baseBranch`、`createdAt`。现有 `WorktreeInfo` 和 `WorktreeDetailedStatus` 增加 `baseBranch: string | null`。
+
+## 数据流
+
+创建流程：
+
+1. `clawt create` 完成前置检查。
+2. `createWorktrees()` 在创建前读取 `getCurrentBranch()`。
+3. 每成功创建一个 worktree 和 validate 分支后，写入对应 metadata 文件。
+4. 命令输出继续展示目录、分支、验证分支；是否在创建输出中展示来源分支由实现保持简洁，可不新增。
+
+读取流程：
+
+1. `getProjectWorktrees()` 扫描 `~/.clawt/worktrees/<projectName>/` 并与 `git worktree list` 交叉验证。
+2. 对每个有效 worktree 读取 `~/.clawt/projects/<projectName>/worktrees/<branch>.json`。
+3. 返回 `WorktreeInfo` 时带上 `baseBranch`，没有元数据时为 `null`。
+4. `status` 的收集层把 `baseBranch` 传入 `WorktreeDetailedStatus`。
+5. `list`、`status` 文本渲染和交互面板只负责展示已有字段。
+
+## 展示规则
+
+`clawt status` 普通文本输出中，每个 worktree 条目增加一行：
+
+```text
+来源分支: test
+```
+
+英文语言环境显示：
+
+```text
+Base branch: test
+```
+
+没有元数据时显示：
+
+```text
+来源分支: 未记录
+```
+
+英文语言环境显示：
+
+```text
+Base branch: Not recorded
+```
+
+`clawt status -i` 交互面板在每个 worktree 块中同样显示来源分支行。
+
+`clawt list` 文本输出在路径与分支行中追加来源分支：
+
+```text
+~/.clawt/worktrees/project/feature-login   [feature-login]   <- test
+```
+
+没有元数据时：
+
+```text
+~/.clawt/worktrees/project/feature-login   [feature-login]   <- 未记录
+```
+
+JSON 输出新增 `baseBranch` 字段：
+
+```json
+{
+  "path": "~/.clawt/worktrees/project/feature-login",
+  "branch": "feature-login",
+  "baseBranch": "test"
+}
+```
+
+历史 worktree 无元数据时：
+
+```json
+{
+  "path": "~/.clawt/worktrees/project/legacy",
+  "branch": "legacy",
+  "baseBranch": null
+}
+```
+
+## 清理规则
+
+`cleanupWorktrees()` 删除 worktree、普通分支和 validate 分支时，同步删除对应 metadata 文件。删除 metadata 失败不阻断主清理流程，只记录日志。
+
+## 错误处理
+
+- 元数据文件不存在：返回 `null`，展示未记录。
+- 元数据 JSON 解析失败：记录 warning，返回 `null`。
+- 保存 metadata 失败：记录错误并抛出，让创建流程暴露问题，因为创建后无法记录来源会削弱防误操作能力。
+- 删除 metadata 失败：记录错误，不影响删除 worktree 的主流程。
+
+## 测试要求
+
+- `createWorktrees()` 和 `createWorktreesByBranches()` 创建成功后写入 `baseBranch`。
+- `getProjectWorktrees()` 能读取已有 `baseBranch`，缺失时返回 `null`。
+- `cleanupWorktrees()` 删除对应 metadata。
+- `clawt list --json` 输出 `baseBranch`。
+- `clawt status --json` 输出 `baseBranch`。
+- `status` 文本输出和 `status -i` 渲染显示来源分支。
+- 元数据解析失败不导致 status/list 崩溃。
+
+## 验收标准
+
+- 新创建的 worktree 在 `status`、`status -i`、`list` 中能看到来源分支。
+- 旧 worktree 没有 metadata 时显示未记录，JSON 为 `null`。
+- 删除 worktree 时对应 metadata 文件被清理。
+- 现有 `status`、`list`、`create` 单元测试通过，新增测试覆盖来源分支功能。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "3.10.5",
+  "version": "3.10.6",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/list.ts

@@ -11,9 +11,10 @@ import {
   formatWorktreeStatus,
   isWorktreeIdle,
   printInfo,
+  formatBaseBranchInline,
 } from '../utils/index.js';
 import { getCurrentLanguage } from '../utils/i18n.js';
-// getWorktreeStatus 和 formatWorktreeStatus 仅在文本模式下使用
+// getWorktreeStatus、formatWorktreeStatus 和 formatBaseBranchInline 仅在文本模式下使用
 
 /**
  * 注册 list 命令：列出当前项目所有 worktree
@@ -50,7 +51,7 @@ async function handleList(options: ListOptions): Promise<void> {
 }
 
 /**
- * 以 JSON 格式输出 worktree 列表（仅包含 path 和 branch）
+ * 以 JSON 格式输出 worktree 列表（包含 path、branch 和 baseBranch）
  * @param {string} projectName - 项目名称
  * @param {import('../types/index.js').WorktreeInfo[]} worktrees - worktree 列表
  */
@@ -61,6 +62,7 @@ function printListAsJson(projectName: string, worktrees: import('../types/index.
     worktrees: worktrees.map((wt) => ({
       path: wt.path,
       branch: wt.branch,
+      baseBranch: wt.baseBranch,
     })),
   };
 
@@ -87,7 +89,7 @@ function printListAsText(projectName: string, worktrees: import('../types/index.
       const isIdle = status ? isWorktreeIdle(status) : false;
       const pathDisplay = isIdle ? chalk.hex('#FF8C00')(wt.path) : wt.path;
 
-      printInfo(`  ${pathDisplay}   [${wt.branch}]`);
+      printInfo(`  ${pathDisplay}   [${wt.branch}]   ${formatBaseBranchInline(wt.baseBranch)}`);
 
       if (status) {
         printInfo(`    ${formatWorktreeStatus(status)}`);

package/src/commands/merge.ts

@@ -155,7 +155,7 @@ async function shouldCleanupAfterMerge(branchName: string): Promise<boolean> {
  * @param {string} branchName - 分支名
  */
 function cleanupWorktreeAndBranch(worktreePath: string, branchName: string): void {
-  cleanupWorktrees([{ path: worktreePath, branch: branchName }]);
+  cleanupWorktrees([{ path: worktreePath, branch: branchName, baseBranch: null }]);
   printSuccess(MESSAGES.WORKTREE_CLEANED(branchName));
 }
 

package/src/commands/remove.ts

@@ -24,6 +24,7 @@ import {
   getValidateBranchName,
   deleteValidateBranch,
   getCurrentBranch,
+  removeWorktreeMetadata,
 } from '../utils/index.js';
 import type { WorktreeMultiResolveMessages } from '../utils/index.js';
 import { getCurrentLanguage } from '../utils/i18n.js';
@@ -120,6 +121,8 @@ async function handleRemove(options: RemoveOptions): Promise<void> {
       deleteValidateBranch(wt.branch);
       // 清理该分支对应的 validate 快照
       removeSnapshot(projectName, wt.branch);
+      // 清理该分支的来源分支元数据
+      removeWorktreeMetadata(projectName, wt.branch);
       printSuccess(MESSAGES.WORKTREE_REMOVED(wt.path));
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);

package/src/commands/status.ts

@@ -23,6 +23,7 @@ import {
   InteractivePanel,
   loadProjectConfig,
   checkBranchExists,
+  formatBaseBranchLine,
 } from '../utils/index.js';
 import { getCurrentLanguage } from '../utils/i18n.js';
 
@@ -141,6 +142,7 @@ async function collectWorktreeDetailedStatusAsync(worktree: WorktreeInfo, projec
     insertions: diffStat.insertions,
     deletions: diffStat.deletions,
     createdAt,
+    baseBranch: worktree.baseBranch,
   };
 }
 
@@ -362,6 +364,9 @@ function printWorktreeItem(wt: WorktreeDetailedStatus): void {
     printInfo(`    ${chalk.green(lang === 'en' ? 'In sync with main' : '与主分支同步')}`);
   }
 
+  // 来源分支
+  printInfo(`    ${chalk.gray(formatBaseBranchLine(wt.baseBranch))}`);
+
   // 分支创建时间
   if (wt.createdAt) {
     const relativeTime = formatRelativeTime(wt.createdAt);

package/src/types/status.ts

@@ -18,6 +18,8 @@ export interface WorktreeDetailedStatus {
   deletions: number;
   /** 分支创建时间（首次分叉提交的 ISO 8601 时间字符串），无分叉提交时为 null */
   createdAt: string | null;
+  /** 创建 worktree 时所在的来源分支，无元数据时为 null */
+  baseBranch: string | null;
 }
 
 /** 主 worktree 状态信息 */

package/src/types/worktree.ts

@@ -1,9 +1,21 @@
+/** worktree 来源分支元数据 */
+export interface WorktreeMetadata {
+  /** worktree 分支名 */
+  branch: string;
+  /** 创建 worktree 时所在的真实当前分支 */
+  baseBranch: string;
+  /** 元数据创建时间 */
+  createdAt: string;
+}
+
 /** worktree 信息 */
 export interface WorktreeInfo {
   /** worktree 路径 */
   path: string;
   /** 分支名 */
   branch: string;
+  /** 创建 worktree 时所在的来源分支，无元数据时为 undefined 或 null */
+  baseBranch?: string | null;
 }
 
 /** worktree 变更统计信息 */

package/src/utils/formatter.ts

@@ -245,6 +245,28 @@ export function formatLocalISOString(date: Date): string {
   return `${iso}${sign}${hours}:${minutes}`;
 }
 
+/**
+ * 格式化来源分支展示行（用于 status 文本输出和交互面板）
+ * @param {string | null | undefined} baseBranch - 来源分支
+ * @returns {string} 格式化的来源分支文本，如 "来源分支: test" 或 "来源分支: 未记录"
+ */
+export function formatBaseBranchLine(baseBranch: string | null | undefined): string {
+  const lang = getCurrentLanguage();
+  const label = lang === 'en' ? 'Base branch' : '来源分支';
+  const fallback = lang === 'en' ? 'Not recorded' : '未记录';
+  return `${label}: ${baseBranch ?? fallback}`;
+}
+
+/**
+ * 格式化来源分支内联展示（用于 list 文本输出）
+ * @param {string | null | undefined} baseBranch - 来源分支
+ * @returns {string} 格式化的来源分支内联文本，如 "<- test" 或 "<- 未记录"
+ */
+export function formatBaseBranchInline(baseBranch: string | null | undefined): string {
+  const fallback = getCurrentLanguage() === 'en' ? 'Not recorded' : '未记录';
+  return `<- ${baseBranch ?? fallback}`;
+}
+
 /**
  * 生成任务模板文件名，格式：clawt-tasks-YYYY-MM-DD-HH-mm-ss.md
  * @param {string} prefix - 文件名前缀

package/src/utils/index.ts

@@ -70,12 +70,13 @@ export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled
 export type { PreCheckOptions } from './validation.js';
 export { createWorktrees, getProjectWorktrees, getProjectWorktreeDir, cleanupWorktrees, getWorktreeStatus, createWorktreesByBranches } from './worktree.js';
 export { loadConfig, writeDefaultConfig, writeConfig, saveConfig, getConfigValue, ensureClawtDirs, parseConcurrency } from './config.js';
-export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime, formatDiskSize, formatLocalISOString, generateTaskFilename } from './formatter.js';
+export { printSuccess, printError, printWarning, printInfo, printHint, printSeparator, printDoubleSeparator, confirmAction, confirmDestructiveAction, formatWorktreeStatus, isWorktreeIdle, formatDuration, formatRelativeTime, formatDiskSize, formatLocalISOString, generateTaskFilename, formatBaseBranchLine, formatBaseBranchInline } from './formatter.js';
 export { ensureDir, removeEmptyDir, calculateDirSize } from './fs.js';
 export { removeExternalSymlinks } from './symlink-guard.js';
 export { multilineInput, promptCommitMessage } from './prompt.js';
 export { launchInteractiveClaude, hasClaudeSessionHistory, launchInteractiveClaudeInNewTerminal } from './claude.js';
 export { getSnapshotPath, hasSnapshot, getSnapshotModifiedTime, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots, getProjectSnapshotBranches } from './validate-snapshot.js';
+export { removeWorktreeMetadata } from './worktree-metadata.js';
 export { findExactMatch, findFuzzyMatches, promptGroupedMultiSelectBranches, resolveTargetWorktree, resolveTargetWorktrees, groupWorktreesByDate, buildGroupedChoices, buildGroupMembershipMap, formatRelativeDate, getWorktreeCreatedDate, getWorktreeCreatedTime } from './worktree-matcher.js';
 export type { WorktreeResolveMessages, WorktreeMultiResolveMessages } from './worktree-matcher.js';
 export { ProgressRenderer } from './progress.js';

package/src/utils/interactive-panel-render.ts

@@ -30,7 +30,7 @@ import {
   PANEL_COMMITS_BEHIND,
 } from '../constants/messages/index.js';
 import type { StatusResult, WorktreeDetailedStatus, MainWorktreeStatus } from '../types/index.js';
-import { formatRelativeTime, groupWorktreesByDate, formatRelativeDate } from './index.js';
+import { formatRelativeTime, groupWorktreesByDate, formatRelativeDate, formatBaseBranchLine } from './index.js';
 
 /** 面板行类型 */
 export interface PanelLine {
@@ -136,7 +136,7 @@ export function buildPanelFrame(
  * @returns {number[]} 按显示顺序排列的原始索引数组
  */
 export function buildDisplayOrder(worktrees: WorktreeDetailedStatus[]): number[] {
-  const worktreeInfos = worktrees.map((wt) => ({ path: wt.path, branch: wt.branch }));
+  const worktreeInfos = worktrees.map((wt) => ({ path: wt.path, branch: wt.branch, baseBranch: wt.baseBranch }));
   const groups = groupWorktreesByDate(worktreeInfos);
 
   // 构建分支名到原始索引的映射
@@ -164,7 +164,7 @@ export function buildGroupedWorktreeLines(worktrees: WorktreeDetailedStatus[], s
   const panelLines: PanelLine[] = [];
 
   // 构建临时 WorktreeInfo 兼容结构用于分组（groupWorktreesByDate 需要 path 字段）
-  const worktreeInfos = worktrees.map((wt) => ({ path: wt.path, branch: wt.branch }));
+  const worktreeInfos = worktrees.map((wt) => ({ path: wt.path, branch: wt.branch, baseBranch: wt.baseBranch }));
   const groups = groupWorktreesByDate(worktreeInfos);
 
   // 构建分支名到原始索引的映射
@@ -259,6 +259,9 @@ export function renderWorktreeBlock(wt: WorktreeDetailedStatus, isSelected: bool
     lines.push(`${indent}${chalk.green(PANEL_SYNCED_WITH_MAIN)}`);
   }
 
+  // 来源分支
+  lines.push(`${indent}${chalk.gray(formatBaseBranchLine(wt.baseBranch))}`);
+
   // 分支创建时间
   if (wt.createdAt) {
     const relativeTime = formatRelativeTime(wt.createdAt);

package/src/utils/worktree-metadata.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { PROJECTS_CONFIG_DIR } from '../constants/index.js';
+import { safeStringify } from './json.js';
+import { ensureDir } from './fs.js';
+import { logger } from '../logger/index.js';
+import type { WorktreeMetadata } from '../types/worktree.js';
+
+/**
+ * 获取 worktree 元数据文件路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {string} 元数据文件路径
+ */
+export function getWorktreeMetadataPath(projectName: string, branchName: string): string {
+  return join(PROJECTS_CONFIG_DIR, projectName, 'worktrees', `${branchName}.json`);
+}
+
+/**
+ * 保存 worktree 来源分支元数据
+ * @param {string} projectName - 项目名
+ * @param {WorktreeMetadata} metadata - 元数据
+ */
+export function saveWorktreeMetadata(projectName: string, metadata: WorktreeMetadata): void {
+  const metadataPath = getWorktreeMetadataPath(projectName, metadata.branch);
+  const metadataDir = dirname(metadataPath);
+
+  try {
+    ensureDir(metadataDir);
+    writeFileSync(metadataPath, safeStringify(metadata), 'utf-8');
+  } catch (error) {
+    logger.error(`保存 worktree 元数据失败: ${metadataPath}`, error);
+    throw error;
+  }
+}
+
+/**
+ * 读取 worktree 来源分支元数据
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {WorktreeMetadata | null} 元数据，不存在或解析失败时返回 null
+ */
+export function loadWorktreeMetadata(projectName: string, branchName: string): WorktreeMetadata | null {
+  const metadataPath = getWorktreeMetadataPath(projectName, branchName);
+
+  if (!existsSync(metadataPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(metadataPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    // 校验必要字段，防止不安全的类型断言
+    if (!parsed || typeof parsed !== 'object' || !parsed.branch || !parsed.baseBranch) {
+      logger.warn(`worktree 元数据格式无效: ${metadataPath}`);
+      return null;
+    }
+    return parsed as WorktreeMetadata;
+  } catch (error) {
+    logger.warn(`解析 worktree 元数据失败: ${metadataPath}`, error);
+    return null;
+  }
+}
+
+/**
+ * 删除 worktree 来源分支元数据
+ *
+ * 删除失败时仅记录日志，不抛出异常（best-effort 语义）。
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ */
+export function removeWorktreeMetadata(projectName: string, branchName: string): void {
+  const metadataPath = getWorktreeMetadataPath(projectName, branchName);
+
+  try {
+    if (existsSync(metadataPath)) {
+      rmSync(metadataPath);
+    }
+  } catch (error) {
+    logger.error(`删除 worktree 元数据失败: ${metadataPath}`, error);
+  }
+}

package/src/utils/worktree.ts

@@ -6,6 +6,8 @@ import { createWorktree as gitCreateWorktree, getProjectName, gitWorktreeList, r
 import { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 import { ensureDir, removeEmptyDir } from './fs.js';
 import { createValidateBranch, deleteValidateBranch } from './validate-branch.js';
+import { getCurrentBranch } from './git-branch.js';
+import { saveWorktreeMetadata, loadWorktreeMetadata, removeWorktreeMetadata } from './worktree-metadata.js';
 import type { WorktreeInfo, WorktreeStatus } from '../types/index.js';
 
 /**
@@ -34,17 +36,22 @@ export function createWorktrees(branchName: string, count: number): WorktreeInfo
   // 3. 校验所有分支是否都不存在（在创建任何 worktree 之前）
   validateBranchesNotExist(branchNames);
 
-  // 4. 确保项目 worktree 目录存在
-  const projectDir = getProjectWorktreeDir();
+  // 4. 获取项目名并确保 worktree 目录存在
+  const projectName = getProjectName();
+  const projectDir = join(WORKTREES_DIR, projectName);
   ensureDir(projectDir);
 
-  // 5. 串行创建 worktree 及对应验证分支
+  // 5. 记录当前分支作为来源分支
+  const baseBranch = getCurrentBranch();
+
+  // 6. 串行创建 worktree 及对应验证分支，并保存元数据
   const results: WorktreeInfo[] = [];
   for (const name of branchNames) {
     const worktreePath = join(projectDir, name);
     gitCreateWorktree(name, worktreePath);
     createValidateBranch(name);
-    results.push({ path: worktreePath, branch: name });
+    saveWorktreeMetadata(projectName, { branch: name, baseBranch, createdAt: new Date().toISOString() });
+    results.push({ path: worktreePath, branch: name, baseBranch });
     logger.info(`worktree 创建完成: ${worktreePath} (分支: ${name})`);
   }
 
@@ -62,17 +69,22 @@ export function createWorktreesByBranches(branchNames: string[]): WorktreeInfo[]
   // 1. 校验所有分支是否都不存在
   validateBranchesNotExist(branchNames);
 
-  // 2. 确保项目 worktree 目录存在
-  const projectDir = getProjectWorktreeDir();
+  // 2. 获取项目名并确保 worktree 目录存在
+  const projectName = getProjectName();
+  const projectDir = join(WORKTREES_DIR, projectName);
   ensureDir(projectDir);
 
-  // 3. 串行创建 worktree 及对应验证分支
+  // 3. 记录当前分支作为来源分支
+  const baseBranch = getCurrentBranch();
+
+  // 4. 串行创建 worktree 及对应验证分支，并保存元数据
   const results: WorktreeInfo[] = [];
   for (const name of branchNames) {
     const worktreePath = join(projectDir, name);
     gitCreateWorktree(name, worktreePath);
     createValidateBranch(name);
-    results.push({ path: worktreePath, branch: name });
+    saveWorktreeMetadata(projectName, { branch: name, baseBranch, createdAt: new Date().toISOString() });
+    results.push({ path: worktreePath, branch: name, baseBranch });
     logger.info(`worktree 创建完成: ${worktreePath} (分支: ${name})`);
   }
 
@@ -85,7 +97,8 @@ export function createWorktreesByBranches(branchNames: string[]): WorktreeInfo[]
  * @returns {WorktreeInfo[]} 有效的 worktree 列表
  */
 export function getProjectWorktrees(): WorktreeInfo[] {
-  const projectDir = getProjectWorktreeDir();
+  const projectName = getProjectName();
+  const projectDir = join(WORKTREES_DIR, projectName);
 
   if (!existsSync(projectDir)) {
     return [];
@@ -107,9 +120,12 @@ export function getProjectWorktrees(): WorktreeInfo[] {
     const fullPath = join(projectDir, entry.name);
     // 交叉验证：路径必须在 git worktree list 中
     if (registeredPaths.has(fullPath)) {
+      // 读取来源分支元数据，无元数据时 baseBranch 为 null
+      const metadata = loadWorktreeMetadata(projectName, entry.name);
       worktrees.push({
         path: fullPath,
         branch: entry.name,
+        baseBranch: metadata?.baseBranch ?? null,
       });
     }
   }
@@ -122,18 +138,21 @@ export function getProjectWorktrees(): WorktreeInfo[] {
  * @param {WorktreeInfo[]} worktrees - 待清理的 worktree 列表
  */
 export function cleanupWorktrees(worktrees: WorktreeInfo[]): void {
+  const projectName = getProjectName();
   for (const wt of worktrees) {
     try {
       removeWorktreeByPath(wt.path);
       deleteBranch(wt.branch);
       deleteValidateBranch(wt.branch);
+      // 删除来源分支元数据
+      removeWorktreeMetadata(projectName, wt.branch);
       logger.info(`已清理 worktree 和分支: ${wt.branch}`);
     } catch (error) {
       logger.error(`清理 worktree 失败: ${wt.path} - ${error}`);
     }
   }
   gitWorktreePrune();
-  const projectDir = getProjectWorktreeDir();
+  const projectDir = join(WORKTREES_DIR, projectName);
   removeEmptyDir(projectDir);
 }
 

package/tests/helpers/fixtures.ts

@@ -9,6 +9,7 @@ export function createWorktreeInfo(overrides: Partial<WorktreeInfo> = {}): Workt
   return {
     path: '/Users/test/.clawt/worktrees/my-project/feature-branch',
     branch: 'feature-branch',
+    baseBranch: null,
     ...overrides,
   };
 }

package/tests/unit/commands/cover-validate.test.ts

@@ -45,8 +45,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   getProjectName: vi.fn().mockReturnValue('test-project'),
   getGitTopLevel: vi.fn().mockReturnValue('/repo'),
   getCurrentBranch: vi.fn().mockReturnValue('clawt-validate-feature'),
-  getProjectWorktrees: vi.fn().mockReturnValue([{ path: '/path/feature', branch: 'feature' }]),
-  findExactMatch: vi.fn().mockReturnValue({ path: '/path/feature', branch: 'feature' }),
+  getProjectWorktrees: vi.fn().mockReturnValue([{ path: '/path/feature', branch: 'feature', baseBranch: null }]),
+  findExactMatch: vi.fn().mockReturnValue({ path: '/path/feature', branch: 'feature', baseBranch: null }),
   hasSnapshot: vi.fn().mockReturnValue(true),
   readSnapshot: vi.fn().mockReturnValue({ treeHash: 'snapshot-tree-hash', headCommitHash: '', stagedTreeHash: '' }),
   writeSnapshot: vi.fn(),
@@ -103,8 +103,8 @@ beforeEach(() => {
   vi.clearAllMocks();
   // 恢复默认 mock 值
   mockedGetCurrentBranch.mockReturnValue('clawt-validate-feature');
-  mockedGetProjectWorktrees.mockReturnValue([{ path: '/path/feature', branch: 'feature' }]);
-  mockedFindExactMatch.mockReturnValue({ path: '/path/feature', branch: 'feature' });
+  mockedGetProjectWorktrees.mockReturnValue([{ path: '/path/feature', branch: 'feature', baseBranch: null }]);
+  mockedFindExactMatch.mockReturnValue({ path: '/path/feature', branch: 'feature', baseBranch: null });
   mockedHasSnapshot.mockReturnValue(true);
   mockedReadSnapshot.mockReturnValue({ treeHash: 'snapshot-tree-hash', headCommitHash: '', stagedTreeHash: '' });
   mockedIsWorkingDirClean.mockReturnValue(false);

package/tests/unit/commands/create.test.ts

@@ -67,7 +67,7 @@ describe('registerCreateCommand', () => {
 describe('handleCreate', () => {
   it('成功创建 worktree', async () => {
     mockedCreateWorktrees.mockReturnValue([
-      { path: '/path/feature', branch: 'feature' },
+      { path: '/path/feature', branch: 'feature', baseBranch: null },
     ]);
 
     const program = new Command();
@@ -82,8 +82,8 @@ describe('handleCreate', () => {
 
   it('支持 -n 指定创建数量', async () => {
     mockedCreateWorktrees.mockReturnValue([
-      { path: '/path/feature-1', branch: 'feature-1' },
-      { path: '/path/feature-2', branch: 'feature-2' },
+      { path: '/path/feature-1', branch: 'feature-1', baseBranch: null },
+      { path: '/path/feature-2', branch: 'feature-2', baseBranch: null },
     ]);
 
     const program = new Command();