[ckpt] bug: workspace 包含指向自身的绝对路径 symlink 时，checkpoint (auto-init) rsync 失败 (exit code 23)

[zhangtaibo]

Component

ckpt

Bug Description

当一个尚未初始化的 workspace 目录中包含指向 workspace 内部文件的绝对路径 symlink 时，首次执行 ws-ckpt checkpoint（触发 auto-init）会失败，报错：

Error [InternalError]: rsync failed with exit code: Some(23)

rsync exit code 23 表示 "Partial transfer due to error"。

根因分析：auto-init 过程中，ws-ckpt 使用 rsync 将原始目录内容复制到 btrfs subvolume。当 workspace 包含绝对路径 symlink（如 link.txt -> /root/.openclaw/workspace/target.txt）时，rsync 在复制过程中遇到 symlink 目标路径解析问题——原始路径 /root/.openclaw/workspace/ 在 init 过程中可能已被替换为 symlink，导致路径循环或目标不可访问。

影响：

• checkpoint 命令返回非零退出码，快照不会创建
• workspace 也不会被初始化（仍为普通目录）
• 调用方可以感知到错误（不像 [ckpt] bug: workspace symlink 被外部删除后，ws-ckpt init 静默成功但不重建 symlink，导致 checkpoint/rollback 失效 #694 是静默失败）

对比：

• 相对路径 symlink（ln -s target.txt link.txt）→ 正常工作 ✓
• 指向 workspace 外部的绝对 symlink（ln -s /etc/hostname link.txt）→ 正常工作 ✓
• 已初始化 workspace（已是 symlink）中的绝对路径内部 symlink → 正常工作 ✓
• 仅未初始化 workspace（普通目录）+ 绝对路径内部 symlink → 失败 ✗

Steps to Reproduce

WS=~/.openclaw/workspace

# 1. 确保 workspace 不存在（或已 recover）
ws-ckpt recover -w $WS --force 2>/dev/null || true
rm -rf $WS

# 2. 创建普通目录 + 文件 + 绝对路径内部 symlink
mkdir -p $WS
echo "hello" > $WS/target.txt
ln -s $WS/target.txt $WS/link.txt       # 绝对路径指向自身内部

# 3. 验证目录状态
file $WS                                 # directory（非 symlink）
ls -la $WS/link.txt                      # -> /root/.openclaw/workspace/target.txt

# 4. BUG — checkpoint (auto-init) 失败
ws-ckpt checkpoint -w $WS -i test -m "test"
# 输出: Error [InternalError]: rsync failed with exit code: Some(23)
# 退出码: 1

Expected Behavior

ws-ckpt checkpoint 在 auto-init 过程中应正确处理 workspace 内部的绝对路径 symlink：

• 方案 A（推荐）：auto-init 的 rsync 使用 --copy-links 或 --safe-links 选项，确保绝对路径 symlink 在复制过程中被正确处理
• 方案 B：在 rsync 前将绝对路径内部 symlink 转换为相对路径 symlink
• 方案 C：给出更明确的错误信息，提示用户将绝对路径 symlink 转换为相对路径后重试

Environment

• OS: Alibaba Cloud Linux 4.0.3 (Agentic Edition)
• Kernel: 6.6.102-5.4.3.alnx4.x86_64
• ws-ckpt 版本: 0.3.3
• 文件系统: btrfs on /dev/loop0 (/mnt/btrfs-workspace)
• ws-ckpt daemon: active (running)

Relevant Log Output

=== 场景: 普通目录 + 绝对路径内部 symlink + 首次 checkpoint (auto-init) ===
创建前目录类型:
/root/.openclaw/workspace: directory
total 12
drwxr-xr-x  2 root root 4096 Jun  9 15:07 .
drwx------ 12 root root 4096 Jun  9 15:07 ..
lrwxrwxrwx  1 root root   36 Jun  9 15:07 link.txt -> /root/.openclaw/workspace/target.txt
-rw-r--r--  1 root root    6 Jun  9 15:07 target.txt

=== 首次 checkpoint (触发 auto-init) ===
Error [InternalError]: rsync failed with exit code: Some(23)
退出码: 1

=== 目录状态 (未初始化，仍为普通目录) ===
/root/.openclaw/workspace: directory
total 12
drwxr-xr-x  2 root root 4096 Jun  9 15:07 .
drwx------ 12 root root 4096 Jun  9 15:07 ..
lrwxrwxrwx  1 root root   36 Jun  9 15:07 link.txt -> /root/.openclaw/workspace/target.txt
-rw-r--r--  1 root root    6 Jun  9 15:07 target.txt
No snapshots found.

Additional Context

对比测试（相对路径 symlink 正常工作）：

# 同样的场景，使用相对路径 symlink
rm -rf $WS && mkdir -p $WS
echo "hello" > $WS/target.txt
ln -s target.txt $WS/link.txt            # 相对路径
ws-ckpt checkpoint -w $WS -i test -m "test"
# 输出: ✓ Checkpoint created: test        ← 正常工作

实际触发场景：AI Agent 工作目录中 IDE 或构建工具（如 npm、yarn、Python venv）经常创建包含绝对路径 symlink 的目录结构（如 node_modules/.bin/ 中的 symlink、.venv/bin/python -> /usr/bin/python3），当这些 symlink 碰巧指向 workspace 内部时就会触发此 bug。

临时绕过方案：在 init/checkpoint 前，先使用 ws-ckpt init -w $WS 显式初始化，确保 workspace 已是 symlink，然后再添加绝对路径 symlink 文件并 checkpoint——已初始化的 workspace 不受此 bug 影响。

[github-actions]

🔀 Issue Triage

This issue has been automatically assigned to @Ziqi002 as the maintainer(s) of ckpt.

Maintainers, please review and triage this issue. Set a priority label and update the status as needed. Thanks! 🙏