bug: macOS records fail with "insert failed: inserting block"

[Kisechan]

Environment

• recall: 0.1.0, built from current master
• macOS: 27.0 (26A428), arm64
• Hardware: MacBook Air M4
• Shell: zsh 5.9
• Terminal session: recall shell

Steps to reproduce

1. Start a proxied shell:

   recall shell

2. Run a command that produces normal terminal output:

   hyfetch

Actual behavior

The command renders successfully, then recall prints:

recall: insert failed: inserting block

The block is not persisted to recall history.

Expected behavior

recall stores the command metadata and output as a block without printing an insert error.

Additional context

• The failure appeared during a normal interactive zsh session on macOS.
• The command output contains ANSI color sequences and Unicode characters.
• Screenshot attached.

[wendaining]

根因深度剖析与重现诊断 / Root Cause Analysis

我们在 #16 中曾经深入排查过这个错误，并在 commit 7102165 和 6ddc4e4 中做出了两项关键修复：

1. 重试机制：对 SQLite 的 SQLITE_BUSY 与 SQLITE_LOCKED 增加了重试退避（retry_on_busy）。
2. 重定向终端输出到独立日志文件：将原本直接 eprintln! 输出到终端屏幕（破坏 PTY 画面）的错误，重定向写入到数据库同级目录下的 recall-errors.log 文件（log_writer_error），并在 doctor 命令中增加了路径提示。

基于上述修复，只要运行的是包含上述 commit 的最新代码，终端屏幕上就绝对不会再出现这行 recall: insert failed: inserting block 的裸文本输出。

为什么该问题在用户环境中再次复现？

主要存在以下两种可能原因：

1. 环境运行的是旧二进制，未生效最新变更（最常见）

   • 查看 Issue 报告的环境信息：用户标注 recall 版本为 0.1.0。
   • Release v0.2.0 刚刚发布不久，如果用户是通过之前的脚本或 brew/cargo 安装的旧版本 v0.1.0，此时运行的仍是没有包含 commit 6ddc4e4 的旧二进制。
   • 可以通过 which recall 查看当前路径，或者运行 recall --version 确认当前生效的二进制是否是真正的最新版本。

2. 数据库存在非并发锁类的永久性错误（Permanent Failure）

   • 即使在更新后，如果底层出现了非 SQLITE_BUSY 的错误（例如：
     • recall.db 文件或其上级目录存在权限问题；
     • 数据库文件由旧版本/不同用户创建导致只读；
     • 磁盘空间不足；
     • SQLite Schema 损坏或未对齐的唯一索引冲突；
   • retry_on_busy 遇到非锁错误会立刻放弃重试并抛出，随后被记录下来。

---

推荐排查与修复步骤 / Recommended Steps

1. 更新 recall 至最新版本：
   请确保运行的是最新的构建（v0.2.0 或 master 最新 commit）：

   # 检查当前生效的二进制路径与版本
   which recall
   recall --version

2. 查看错误日志以获取真正的底层 SQLite 报错：
   在新版本中，所有写入失败的完整错误链都会被记录下来，可通过以下命令定位真实原因：

   # 运行 doctor 查看数据库与日志路径
   recall doctor
   
   # 或者直接查看 recall 错误日志
   cat ~/.local/share/recall/recall-errors.log
   # （若自定义了路径，请查看对应 DB 目录下的 recall-errors.log）

3. 检查数据库文件权限：

   ls -la ~/.local/share/recall/