clawt 2.16.1 → 2.16.3

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

@@ -17,7 +17,11 @@ vi.mock('../../../src/constants/index.js', () => ({
     STATUS_CHANGE_UNCOMMITTED: '未提交',
     STATUS_CHANGE_CONFLICT: '冲突',
     STATUS_CHANGE_CLEAN: '干净',
-    STATUS_SNAPSHOT_ORPHANED: '(孤立)',
+    STATUS_SNAPSHOT_ORPHANED: (count: number) => `其中 ${count} 个快照对应的 worktree 已不存在`,
+    STATUS_CREATED_AT: (relativeTime: string) => `创建于 ${relativeTime}`,
+    STATUS_NO_DIVERGED_COMMITS: '尚无分叉提交',
+    STATUS_LAST_VALIDATED: (relativeTime: string) => `上次验证: ${relativeTime}`,
+    STATUS_NOT_VALIDATED: '✗ 未验证',
   },
 }));
 
@@ -32,8 +36,10 @@ vi.mock('../../../src/utils/index.js', () => ({
   getDiffStat: vi.fn(),
   hasMergeConflict: vi.fn(),
   hasLocalCommits: vi.fn(),
-  hasSnapshot: vi.fn(),
+  getSnapshotModifiedTime: vi.fn(),
   getProjectSnapshotBranches: vi.fn(),
+  getBranchCreatedAt: vi.fn(),
+  formatRelativeTime: vi.fn(),
   printInfo: vi.fn(),
   printDoubleSeparator: vi.fn(),
   printSeparator: vi.fn(),
@@ -50,8 +56,10 @@ import {
   getDiffStat,
   hasMergeConflict,
   hasLocalCommits,
-  hasSnapshot,
+  getSnapshotModifiedTime,
   getProjectSnapshotBranches,
+  getBranchCreatedAt,
+  formatRelativeTime,
   printInfo,
 } from '../../../src/utils/index.js';
 
@@ -64,8 +72,10 @@ const mockedGetCommitCountBehind = vi.mocked(getCommitCountBehind);
 const mockedGetDiffStat = vi.mocked(getDiffStat);
 const mockedHasMergeConflict = vi.mocked(hasMergeConflict);
 const mockedHasLocalCommits = vi.mocked(hasLocalCommits);
-const mockedHasSnapshot = vi.mocked(hasSnapshot);
+const mockedGetSnapshotModifiedTime = vi.mocked(getSnapshotModifiedTime);
 const mockedGetProjectSnapshotBranches = vi.mocked(getProjectSnapshotBranches);
+const mockedGetBranchCreatedAt = vi.mocked(getBranchCreatedAt);
+const mockedFormatRelativeTime = vi.mocked(formatRelativeTime);
 const mockedPrintInfo = vi.mocked(printInfo);
 
 beforeEach(() => {
@@ -79,7 +89,9 @@ beforeEach(() => {
   mockedGetDiffStat.mockReturnValue({ insertions: 0, deletions: 0 });
   mockedHasMergeConflict.mockReturnValue(false);
   mockedHasLocalCommits.mockReturnValue(false);
-  mockedHasSnapshot.mockReturnValue(false);
+  mockedGetSnapshotModifiedTime.mockReturnValue(null);
+  mockedGetBranchCreatedAt.mockReturnValue(null);
+  mockedFormatRelativeTime.mockReturnValue('3 天前');
   mockedPrintInfo.mockReset();
 });
 
@@ -167,7 +179,7 @@ describe('handleStatus', () => {
     expect(parsed.main.isClean).toBe(false);
   });
 
-  it('存在快照时标识孤立快照', () => {
+  it('快照摘要包含总数和孤立数', () => {
     mockedGetProjectSnapshotBranches.mockReturnValue(['feature', 'deleted-branch']);
     mockedGetProjectWorktrees.mockReturnValue([
       { path: '/path/feature', branch: 'feature' },
@@ -184,9 +196,8 @@ describe('handleStatus', () => {
       try { JSON.parse(call[0]); return true; } catch { return false; }
     });
     const parsed = JSON.parse(jsonCall![0]);
-    expect(parsed.snapshots).toHaveLength(2);
-    expect(parsed.snapshots[0]).toEqual({ branch: 'feature', worktreeExists: true });
-    expect(parsed.snapshots[1]).toEqual({ branch: 'deleted-branch', worktreeExists: false });
+    expect(parsed.snapshots.total).toBe(2);
+    expect(parsed.snapshots.orphaned).toBe(1);
   });
 
   it('uncommitted 变更状态正确检测', () => {
@@ -211,4 +222,112 @@ describe('handleStatus', () => {
     const parsed = JSON.parse(jsonCall![0]);
     expect(parsed.worktrees[0].changeStatus).toBe('uncommitted');
   });
+
+  it('createdAt 字段包含在 JSON 输出中', () => {
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    mockedGetBranchCreatedAt.mockReturnValue('2026-02-20T14:30:00+08:00');
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    const program = new Command();
+    program.exitOverride();
+    registerStatusCommand(program);
+    program.parse(['status', '--json'], { from: 'user' });
+
+    const jsonCall = consoleSpy.mock.calls.find((call) => {
+      try { JSON.parse(call[0]); return true; } catch { return false; }
+    });
+    const parsed = JSON.parse(jsonCall![0]);
+    expect(parsed.worktrees[0].createdAt).toBe('2026-02-20T14:30:00+08:00');
+  });
+
+  it('snapshotTime 字段包含在 JSON 输出中', () => {
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    mockedGetSnapshotModifiedTime.mockReturnValue('2026-02-22T10:00:00.000Z');
+
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    const program = new Command();
+    program.exitOverride();
+    registerStatusCommand(program);
+    program.parse(['status', '--json'], { from: 'user' });
+
+    const jsonCall = consoleSpy.mock.calls.find((call) => {
+      try { JSON.parse(call[0]); return true; } catch { return false; }
+    });
+    const parsed = JSON.parse(jsonCall![0]);
+    expect(parsed.worktrees[0].snapshotTime).toBe('2026-02-22T10:00:00.000Z');
+  });
+
+  it('文本模式显示分支创建时间', () => {
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    mockedGetBranchCreatedAt.mockReturnValue('2026-02-20T14:30:00+08:00');
+    mockedFormatRelativeTime.mockReturnValue('2 天前');
+
+    const program = new Command();
+    program.exitOverride();
+    registerStatusCommand(program);
+    program.parse(['status'], { from: 'user' });
+
+    const printedLines = mockedPrintInfo.mock.calls.map((call) => call[0]);
+    const createdAtLine = printedLines.find((line) => line.includes('创建于'));
+    expect(createdAtLine).toBeDefined();
+  });
+
+  it('文本模式 createdAt 为 null 时不显示创建时间', () => {
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    mockedGetBranchCreatedAt.mockReturnValue(null);
+
+    const program = new Command();
+    program.exitOverride();
+    registerStatusCommand(program);
+    program.parse(['status'], { from: 'user' });
+
+    const printedLines = mockedPrintInfo.mock.calls.map((call) => call[0]);
+    const createdAtLine = printedLines.find((line) => line.includes('创建于'));
+    expect(createdAtLine).toBeUndefined();
+  });
+
+  it('文本模式无快照时显示未验证警示', () => {
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    mockedGetSnapshotModifiedTime.mockReturnValue(null);
+
+    const program = new Command();
+    program.exitOverride();
+    registerStatusCommand(program);
+    program.parse(['status'], { from: 'user' });
+
+    const printedLines = mockedPrintInfo.mock.calls.map((call) => call[0]);
+    const unverifiedLine = printedLines.find((line) => line.includes('未验证'));
+    expect(unverifiedLine).toBeDefined();
+  });
+
+  it('文本模式有快照时显示上次验证时间', () => {
+    mockedGetProjectWorktrees.mockReturnValue([
+      { path: '/path/feature', branch: 'feature' },
+    ]);
+    mockedGetSnapshotModifiedTime.mockReturnValue('2026-02-22T10:00:00.000Z');
+    mockedFormatRelativeTime.mockReturnValue('5 小时前');
+
+    const program = new Command();
+    program.exitOverride();
+    registerStatusCommand(program);
+    program.parse(['status'], { from: 'user' });
+
+    const printedLines = mockedPrintInfo.mock.calls.map((call) => call[0]);
+    const validatedLine = printedLines.find((line) => line.includes('上次验证'));
+    expect(validatedLine).toBeDefined();
+    const unverifiedLine = printedLines.find((line) => line.includes('未验证'));
+    expect(unverifiedLine).toBeUndefined();
+  });
 });

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

@@ -32,6 +32,13 @@ vi.mock('../../../src/constants/index.js', () => ({
     VALIDATE_RUN_SUCCESS: (cmd: string) => `✓ 命令执行完成: ${cmd}`,
     VALIDATE_RUN_FAILED: (cmd: string, code: number) => `✗ 命令失败: ${cmd}，退出码: ${code}`,
     VALIDATE_RUN_ERROR: (cmd: string, msg: string) => `✗ 命令出错: ${msg}`,
+    VALIDATE_PARALLEL_RUN_START: (count: number) => `正在并行执行 ${count} 个命令...`,
+    VALIDATE_PARALLEL_CMD_START: (index: number, total: number, cmd: string) => `[${index}/${total}] ${cmd}`,
+    VALIDATE_PARALLEL_RUN_ALL_SUCCESS: (count: number) => `✓ 全部 ${count} 个命令执行成功`,
+    VALIDATE_PARALLEL_RUN_SUMMARY: (s: number, f: number) => `共 ${s + f} 个命令，${s} 个成功，${f} 个失败`,
+    VALIDATE_PARALLEL_CMD_SUCCESS: (cmd: string) => `  ✓ ${cmd}`,
+    VALIDATE_PARALLEL_CMD_FAILED: (cmd: string, code: number) => `  ✗ ${cmd}（退出码: ${code}）`,
+    VALIDATE_PARALLEL_CMD_ERROR: (cmd: string, msg: string) => `  ✗ ${cmd}（错误: ${msg}）`,
     SEPARATOR: '────',
   },
 }));
@@ -79,6 +86,8 @@ vi.mock('../../../src/utils/index.js', () => ({
   runCommandInherited: vi.fn(),
   printError: vi.fn(),
   printSeparator: vi.fn(),
+  parseParallelCommands: vi.fn(),
+  runParallelCommands: vi.fn(),
 }));
 
 import { registerValidateCommand } from '../../../src/commands/validate.js';
@@ -116,6 +125,8 @@ import {
   runCommandInherited,
   printError,
   printSeparator,
+  parseParallelCommands,
+  runParallelCommands,
 } from '../../../src/utils/index.js';
 
 const mockedGetProjectName = vi.mocked(getProjectName);
@@ -151,6 +162,8 @@ const mockedPrintWarning = vi.mocked(printWarning);
 const mockedRunCommandInherited = vi.mocked(runCommandInherited);
 const mockedPrintError = vi.mocked(printError);
 const mockedPrintSeparator = vi.mocked(printSeparator);
+const mockedParseParallelCommands = vi.mocked(parseParallelCommands);
+const mockedRunParallelCommands = vi.mocked(runParallelCommands);
 
 const worktree = { path: '/path/feature', branch: 'feature' };
 
@@ -188,6 +201,10 @@ beforeEach(() => {
   mockedRunCommandInherited.mockReset();
   mockedPrintError.mockReset();
   mockedPrintSeparator.mockReset();
+  mockedParseParallelCommands.mockReset();
+  mockedRunParallelCommands.mockReset();
+  // 默认让 parseParallelCommands 返回单命令数组，保持旧测试兼容
+  mockedParseParallelCommands.mockImplementation((cmd: string) => [cmd]);
 });
 
 describe('registerValidateCommand', () => {
@@ -516,3 +533,89 @@ describe('--run 选项', () => {
     expect(mockedRunCommandInherited).not.toHaveBeenCalled();
   });
 });
+
+describe('--run 并行命令', () => {
+  /** 设置首次 validate 成功的公共 mock */
+  function setupSuccessfulFirstValidate(): void {
+    mockedIsWorkingDirClean.mockReturnValue(true);
+    mockedHasLocalCommits.mockReturnValue(true);
+    mockedHasSnapshot.mockReturnValue(false);
+    mockedGitDiffBinaryAgainstBranch.mockReturnValue(Buffer.from('diff'));
+    mockedGitWriteTree.mockReturnValue('treehash');
+    mockedGetHeadCommitHash.mockReturnValue('headhash');
+  }
+
+  it('& 分隔的命令触发并行执行', async () => {
+    setupSuccessfulFirstValidate();
+    mockedParseParallelCommands.mockReturnValue(['pnpm test', 'pnpm build']);
+    mockedRunParallelCommands.mockResolvedValue([
+      { command: 'pnpm test', exitCode: 0 },
+      { command: 'pnpm build', exitCode: 0 },
+    ]);
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '-r', 'pnpm test & pnpm build'], { from: 'user' });
+
+    // 应该调用并行执行而非同步执行
+    expect(mockedRunParallelCommands).toHaveBeenCalledWith(['pnpm test', 'pnpm build'], { cwd: '/repo' });
+    expect(mockedRunCommandInherited).not.toHaveBeenCalled();
+    // 全部成功，printSuccess 被调用（validate 成功 + 各命令成功 + 汇总成功）
+    expect(mockedPrintSuccess).toHaveBeenCalled();
+  });
+
+  it('并行执行部分失败时输出错误汇总', async () => {
+    setupSuccessfulFirstValidate();
+    mockedParseParallelCommands.mockReturnValue(['pnpm test', 'pnpm build']);
+    mockedRunParallelCommands.mockResolvedValue([
+      { command: 'pnpm test', exitCode: 1 },
+      { command: 'pnpm build', exitCode: 0 },
+    ]);
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '-r', 'pnpm test & pnpm build'], { from: 'user' });
+
+    expect(mockedRunParallelCommands).toHaveBeenCalled();
+    // 部分失败，应有错误输出
+    expect(mockedPrintError).toHaveBeenCalled();
+  });
+
+  it('单命令走原有同步路径不触发并行', async () => {
+    setupSuccessfulFirstValidate();
+    mockedParseParallelCommands.mockReturnValue(['npm test']);
+    mockedRunCommandInherited.mockReturnValue({
+      pid: 0, output: [], stdout: Buffer.alloc(0), stderr: Buffer.alloc(0),
+      status: 0, signal: null, error: undefined,
+    });
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '-r', 'npm test'], { from: 'user' });
+
+    // 单命令应该走同步路径
+    expect(mockedRunCommandInherited).toHaveBeenCalledWith('npm test', { cwd: '/repo' });
+    expect(mockedRunParallelCommands).not.toHaveBeenCalled();
+  });
+
+  it('&& 命令不触发并行执行', async () => {
+    setupSuccessfulFirstValidate();
+    mockedParseParallelCommands.mockReturnValue(['pnpm lint && pnpm test']);
+    mockedRunCommandInherited.mockReturnValue({
+      pid: 0, output: [], stdout: Buffer.alloc(0), stderr: Buffer.alloc(0),
+      status: 0, signal: null, error: undefined,
+    });
+
+    const program = new Command();
+    program.exitOverride();
+    registerValidateCommand(program);
+    await program.parseAsync(['validate', '-b', 'feature', '-r', 'pnpm lint && pnpm test'], { from: 'user' });
+
+    // && 不拆分，走同步路径
+    expect(mockedRunCommandInherited).toHaveBeenCalledWith('pnpm lint && pnpm test', { cwd: '/repo' });
+    expect(mockedRunParallelCommands).not.toHaveBeenCalled();
+  });
+});

package/tests/unit/utils/formatter.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { formatWorktreeStatus, printSuccess, printError, printWarning, printInfo, printSeparator, printDoubleSeparator, isWorktreeIdle, formatDuration } from '../../../src/utils/formatter.js';
+import { formatWorktreeStatus, printSuccess, printError, printWarning, printInfo, printSeparator, printDoubleSeparator, isWorktreeIdle, formatDuration, formatRelativeTime } from '../../../src/utils/formatter.js';
 import { createWorktreeStatus } from '../../helpers/fixtures.js';
 
 describe('formatWorktreeStatus', () => {
@@ -136,3 +136,44 @@ describe('formatDuration', () => {
     expect(formatDuration(3661000)).toBe('61m01s');
   });
 });
+
+describe('formatRelativeTime', () => {
+  it('不到 1 分钟时返回"刚刚"', () => {
+    const now = new Date();
+    expect(formatRelativeTime(now.toISOString())).toBe('刚刚');
+  });
+
+  it('数分钟前', () => {
+    const date = new Date(Date.now() - 5 * 60 * 1000);
+    expect(formatRelativeTime(date.toISOString())).toBe('5 分钟前');
+  });
+
+  it('数小时前', () => {
+    const date = new Date(Date.now() - 3 * 60 * 60 * 1000);
+    expect(formatRelativeTime(date.toISOString())).toBe('3 小时前');
+  });
+
+  it('数天前', () => {
+    const date = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+    expect(formatRelativeTime(date.toISOString())).toBe('7 天前');
+  });
+
+  it('数月前', () => {
+    const date = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000);
+    expect(formatRelativeTime(date.toISOString())).toBe('2 个月前');
+  });
+
+  it('数年前', () => {
+    const date = new Date(Date.now() - 400 * 24 * 60 * 60 * 1000);
+    expect(formatRelativeTime(date.toISOString())).toBe('1 年前');
+  });
+
+  it('无效日期返回 null', () => {
+    expect(formatRelativeTime('invalid-date')).toBeNull();
+  });
+
+  it('未来时间返回"刚刚"', () => {
+    const future = new Date(Date.now() + 60 * 60 * 1000);
+    expect(formatRelativeTime(future.toISOString())).toBe('刚刚');
+  });
+});

package/tests/unit/utils/git.test.ts

@@ -63,6 +63,7 @@ import {
   getCommitTreeHash,
   gitDiffTree,
   gitApplyCachedCheck,
+  getBranchCreatedAt,
 } from '../../../src/utils/git.js';
 
 const mockedExecCommand = vi.mocked(execCommand);
@@ -574,3 +575,38 @@ describe('getCommitCountBehind', () => {
     expect(getCommitCountBehind('feature')).toBe(0);
   });
 });
+
+describe('getBranchCreatedAt', () => {
+  it('多条 reflog 记录时返回最后一条（分支创建时间）', () => {
+    mockedExecCommand.mockReturnValue('2026-02-21T10:00:00+08:00\n2026-02-20T14:30:00+08:00');
+    expect(getBranchCreatedAt('feature')).toBe('2026-02-20T14:30:00+08:00');
+    expect(mockedExecCommand).toHaveBeenCalledWith(
+      'git reflog show feature --format=%cI',
+      { cwd: undefined },
+    );
+  });
+
+  it('单条 reflog 记录时返回该时间', () => {
+    mockedExecCommand.mockReturnValue('2026-02-20T14:30:00+08:00');
+    expect(getBranchCreatedAt('feature')).toBe('2026-02-20T14:30:00+08:00');
+  });
+
+  it('无 reflog 记录时返回 null', () => {
+    mockedExecCommand.mockReturnValue('');
+    expect(getBranchCreatedAt('feature')).toBeNull();
+  });
+
+  it('命令失败时返回 null', () => {
+    mockedExecCommand.mockImplementation(() => { throw new Error('fail'); });
+    expect(getBranchCreatedAt('feature')).toBeNull();
+  });
+
+  it('传递 cwd 参数', () => {
+    mockedExecCommand.mockReturnValue('2026-02-20T14:30:00+08:00');
+    getBranchCreatedAt('feature', '/repo');
+    expect(mockedExecCommand).toHaveBeenCalledWith(
+      'git reflog show feature --format=%cI',
+      { cwd: '/repo' },
+    );
+  });
+});

package/tests/unit/utils/shell.test.ts

@@ -13,7 +13,7 @@ vi.mock('../../../src/logger/index.js', () => ({
 }));
 
 import { execSync, execFileSync, spawn } from 'node:child_process';
-import { execCommand, execCommandWithInput, spawnProcess, killAllChildProcesses } from '../../../src/utils/shell.js';
+import { execCommand, execCommandWithInput, spawnProcess, killAllChildProcesses, parseParallelCommands } from '../../../src/utils/shell.js';
 
 const mockedExecSync = vi.mocked(execSync);
 const mockedExecFileSync = vi.mocked(execFileSync);
@@ -106,3 +106,44 @@ describe('killAllChildProcesses', () => {
     expect(() => killAllChildProcesses([])).not.toThrow();
   });
 });
+
+describe('parseParallelCommands', () => {
+  it('单个命令返回包含该命令的数组', () => {
+    expect(parseParallelCommands('pnpm test')).toEqual(['pnpm test']);
+  });
+
+  it('使用 & 分隔的多个命令被正确拆分', () => {
+    expect(parseParallelCommands('pnpm test & pnpm build')).toEqual(['pnpm test', 'pnpm build']);
+  });
+
+  it('&& 不会被拆分，保持为单条命令', () => {
+    expect(parseParallelCommands('pnpm lint && pnpm test')).toEqual(['pnpm lint && pnpm test']);
+  });
+
+  it('混合场景：&& 和 & 同时存在', () => {
+    expect(parseParallelCommands('pnpm lint && pnpm test & pnpm build')).toEqual([
+      'pnpm lint && pnpm test',
+      'pnpm build',
+    ]);
+  });
+
+  it('多个 & 分隔的命令', () => {
+    expect(parseParallelCommands('cmd1 & cmd2 & cmd3')).toEqual(['cmd1', 'cmd2', 'cmd3']);
+  });
+
+  it('空字符串返回空数组', () => {
+    expect(parseParallelCommands('')).toEqual([]);
+  });
+
+  it('去除命令首尾空白', () => {
+    expect(parseParallelCommands('  pnpm test  &  pnpm build  ')).toEqual(['pnpm test', 'pnpm build']);
+  });
+
+  it('多个 && 不拆分', () => {
+    expect(parseParallelCommands('cmd1 && cmd2 && cmd3')).toEqual(['cmd1 && cmd2 && cmd3']);
+  });
+
+  it('尾部 & 后无内容时过滤空字符串', () => {
+    expect(parseParallelCommands('pnpm test & ')).toEqual(['pnpm test']);
+  });
+});

package/tests/unit/utils/validate-snapshot.test.ts

@@ -8,6 +8,7 @@ vi.mock('node:fs', () => ({
   unlinkSync: vi.fn(),
   readdirSync: vi.fn(),
   rmdirSync: vi.fn(),
+  statSync: vi.fn(),
 }));
 
 // mock logger
@@ -29,11 +30,12 @@ vi.mock('../../../src/constants/index.js', async (importOriginal) => {
   };
 });
 
-import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, rmdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, rmdirSync, statSync } from 'node:fs';
 import { ensureDir } from '../../../src/utils/fs.js';
 import {
   getSnapshotPath,
   hasSnapshot,
+  getSnapshotModifiedTime,
   readSnapshot,
   readSnapshotTreeHash,
   writeSnapshot,
@@ -48,6 +50,7 @@ const mockedWriteFileSync = vi.mocked(writeFileSync);
 const mockedUnlinkSync = vi.mocked(unlinkSync);
 const mockedReaddirSync = vi.mocked(readdirSync);
 const mockedRmdirSync = vi.mocked(rmdirSync);
+const mockedStatSync = vi.mocked(statSync);
 const mockedEnsureDir = vi.mocked(ensureDir);
 
 describe('getSnapshotPath', () => {
@@ -174,3 +177,20 @@ describe('getProjectSnapshotBranches', () => {
     expect(result).toEqual([]);
   });
 });
+
+describe('getSnapshotModifiedTime', () => {
+  it('快照存在时返回 ISO 时间字符串', () => {
+    mockedExistsSync.mockReturnValue(true);
+    const testDate = new Date('2026-02-22T10:00:00.000Z');
+    // @ts-expect-error statSync 返回类型简化
+    mockedStatSync.mockReturnValue({ mtime: testDate });
+    const result = getSnapshotModifiedTime('proj', 'branch');
+    expect(result).toBe('2026-02-22T10:00:00.000Z');
+  });
+
+  it('快照不存在时返回 null', () => {
+    mockedExistsSync.mockReturnValue(false);
+    const result = getSnapshotModifiedTime('proj', 'branch');
+    expect(result).toBeNull();
+  });
+});