fix(update): recover from incomplete git clean

AGENTS.md

@@ -68,7 +68,7 @@
 - `pi-condense@2.9.1`：总结已完成的工具调用批次，以短 stub 替换历史原始输出，并通过 `context_tree_query` 按需恢复；组合包在用户尚未配置 `contextPrune.enabled` 时默认开启。
 - 根包还固定安装 `@tavily/pi-extension@0.1.2`、`@keenable/pi-search@0.1.2`、`pi-hashline-edit@0.8.3`、`typescript-language-server@5.3.0`、`typescript@6.0.3` 和 `pi-context-view`；`@firstpick/pi-extension-codex-fast-mode`、`@gotgenes/pi-permission-system`、`@smoose/pi-notify`、`@tintinweb/pi-subagents`、`pi-ask-user`、`pi-chrome`、`pi-minimal-footer`、`pi-ssh` 与 `pi-tool-search` 分别指向仓库内对应目录的本地 `file:` 依赖。
 - `install.sh`：先安装根组合包，再交互检查 Hippo Memory CLI、Kitty/Solarized Dark、Oh My Zsh/Powerlevel10k/Zsh 插件、CodeGraph、Kotlin LSP、Java 21+ 和 JDT LS；缺失项目只在用户明确选择 `Y` 后安装或配置。Hippo 项目目录与 `hippo init` 始终由用户自行决定。Powerlevel10k 默认配置来自仓库内置的 `config/p10k.zsh`（当前 Rainbow/ASCII 单行紧凑主题）。
-- `update.sh`：先通过 `pi update` 升级根组合包，再只升级当前已安装的终端环境和机器级依赖；未安装项直接跳过。升级成功后只能调用可定位的更新后组合包 Node helper 检查 Pi agent `settings.json`：只有 `toolSearch` 完整精确匹配旧版 `3` 组 / `20` 工具默认快照时，才创建从生成起即为权限 `600` 的时间戳备份、以同目录临时文件原子迁移到 `5` / `28` 并写入 `bundleDefaultsVersion: 2`；任何自定义或无效配置必须保留，提交前检测到内容变化必须中止。无法从 `PI_PACKAGE_SOURCE` 定位更新后 helper 时必须保留配置并报告失败，不能回退到可能陈旧的脚本目录 helper。其他组件升级前先查询并比较本地与远端版本，只有版本不同时才下载或替换；Powerlevel10k 配置优先从 `pi update` 后的已安装组合包读取，并与 `.zshrc` 受管块一起按内容比较后增量同步。
+- `update.sh`：先通过 `pi update` 升级根组合包，再只升级当前已安装的终端环境和机器级依赖；未安装项直接跳过。不得在 `pi update` 前预清理安装缓存；仅当默认 Git 来源首次升级失败、Pi 的精确中断标记存在、canonical checkout 根目录和 `origin` 均通过身份校验时，才允许对该缓存执行最多 4 次连续 `git clean -fdx`，随后只重试一次 `pi update`，由 Pi 自己恢复依赖和清除标记；自定义来源、标记缺失或身份不匹配必须保持 fail-fast。升级成功后只能调用可定位的更新后组合包 Node helper 检查 Pi agent `settings.json`：只有 `toolSearch` 完整精确匹配旧版 `3` 组 / `20` 工具默认快照时，才创建从生成起即为权限 `600` 的时间戳备份、以同目录临时文件原子迁移到 `5` / `28` 并写入 `bundleDefaultsVersion: 2`；任何自定义或无效配置必须保留，提交前检测到内容变化必须中止。无法从 `PI_PACKAGE_SOURCE` 定位更新后 helper 时必须保留配置并报告失败，不能回退到可能陈旧的脚本目录 helper。其他组件升级前先查询并比较本地与远端版本，只有版本不同时才下载或替换；Powerlevel10k 配置优先从 `pi update` 后的已安装组合包读取，并与 `.zshrc` 受管块一起按内容比较后增量同步。
 - `uninstall.sh`：先移除根组合包；若检测到 Hippo Memory CLI，再明确询问是否卸载确认属于 npm 全局安装的 `hippo-memory`，默认保留且始终不删除 `.hippo/` 或用户记忆数据。其他共享终端环境和机器工具不卸载。
 
 ## 当前职责与默认行为
@@ -258,7 +258,7 @@
 
 组合包依赖或加载入口变化时，至少验证根 `npm install` 幂等、锁文件有效、MCP adapter 唯一所有者不变量测试，以及全部扩展可在隔离的临时 Pi agent 目录加载。权限配置变化时使用仓库内固定快照的 `pi-permission-system` schema 校验，并验证包装入口部署后的文件与仓库源配置一致。
 
-安装、升级、卸载、搜索或 SSH 配置脚本变化时，至少运行 `sh -n install.sh`、`sh -n update.sh`、`sh -n uninstall.sh`、`sh -n search_config.sh`、`sh -n ssh_config.sh` 和 ShellCheck，并核对脚本仍具有可执行权限、仍包含在根 `package.json` 的 `files` 中、README 描述与实际流程一致。Tool Search settings 迁移必须用隔离 agent dir 覆盖完整旧快照迁移、当前值幂等、自定义配置保留、无效 JSON fail-safe、备份/权限、`pi update` 失败不迁移和 `PI_CODING_AGENT_DIR`。搜索配置测试只能使用虚拟 key 和隔离 HOME；SSH 配置测试必须使用隔离 HOME、虚拟凭据与 mock transport，不得连接真实服务器或把真实密码写入测试输出。涉及真实 `pi install`、`pi update`、`pi remove`、Homebrew、远程安装器、Git 克隆、真实 SSH 连接或真实用户终端配置的端到端验证属于外部写操作，未经明确要求不得执行；可以使用隔离的临时 HOME 和 mock 命令验证分支行为。
+安装、升级、卸载、搜索或 SSH 配置脚本变化时，至少运行 `sh -n install.sh`、`sh -n update.sh`、`sh -n uninstall.sh`、`sh -n search_config.sh`、`sh -n ssh_config.sh` 和 ShellCheck，并核对脚本仍具有可执行权限、仍包含在根 `package.json` 的 `files` 中、README 描述与实际流程一致。Git 升级中断恢复必须用隔离 agent dir 和 mock `pi` / `git` 覆盖合法标记连续清理后成功、无标记保持失败、checkout 身份不匹配拒绝清理及单次 Pi 重试边界。Tool Search settings 迁移必须用隔离 agent dir 覆盖完整旧快照迁移、当前值幂等、自定义配置保留、无效 JSON fail-safe、备份/权限、`pi update` 失败不迁移和 `PI_CODING_AGENT_DIR`。搜索配置测试只能使用虚拟 key 和隔离 HOME；SSH 配置测试必须使用隔离 HOME、虚拟凭据与 mock transport，不得连接真实服务器或把真实密码写入测试输出。涉及真实 `pi install`、`pi update`、`pi remove`、Homebrew、远程安装器、Git 克隆、真实 SSH 连接或真实用户终端配置的端到端验证属于外部写操作，未经明确要求不得执行；可以使用隔离的临时 HOME 和 mock 命令验证分支行为。
 
 Hippo 脚本变化必须额外用隔离 HOME/PATH 和 mock `pi`、`npm`、`hippo` 验证：安装缺失 CLI 但不调用 `hippo init`、相同版本不升级、不同版本精确升级、未知来源 CLI 不替换、卸载默认保留、明确确认后只卸载 npm 全局包且保留数据。不得在测试中执行真实全局 npm 写入或修改真实 `.hippo/`。
 

README.md

@@ -77,6 +77,8 @@ Powerlevel10k 主题/配置和各 Zsh 插件使用 `# >>> my-pi:<id> >>>` 到
 pi update git:git@bitbucket.org:siakitem/my-pi.git
 ```
 
+默认 Git 组合包若在 Pi 内部清理大型 `node_modules` 时因目录仍非空而留下 `.pi-update-incomplete` 标记，脚本不会在升级前破坏性预清理。首次 `pi update` 失败后，它只对默认来源推导出的缓存 checkout 进行恢复，并同时校验中断标记、canonical Git 根目录和精确 `origin`；校验通过后最多连续执行 4 次依赖清理，再只重试一次 `pi update`，由 Pi 自己重新安装依赖并清除标记。自定义来源、缺少标记或身份不匹配仍立即失败，不会清理猜测出的路径。
+
 随后只处理已经安装的项目，未安装项直接跳过且不会询问安装：Kitty 及已启用的
 Solarized Dark、Oh My Zsh、Powerlevel10k、两个第三方 Zsh 插件、CodeGraph，以及由
 Homebrew 管理的 Kotlin LSP、Java 21 和 JDT LS。升级前会先刷新或查询对应的远端版本：

tests/update-git-clean-recovery.test.ts

@@ -0,0 +1,160 @@
+import assert from "node:assert/strict";
+import { chmod, copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+async function fixture(
+  t: test.TestContext,
+  options: { createMarker?: boolean; origin?: string; secondPiStatus?: number } = {},
+) {
+  const root = await mkdtemp(join(tmpdir(), "my-pi-update-clean-recovery-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+
+  const home = join(root, "home");
+  const bin = join(root, "bin");
+  const agentDir = join(home, ".pi", "agent");
+  const target = join(agentDir, "git", "bitbucket.org", "siakitem", "my-pi");
+  const marker = join(agentDir, "git", "bitbucket.org", "siakitem", ".my-pi.pi-update-incomplete");
+  const piLog = join(root, "pi.log");
+  const piCount = join(root, "pi.count");
+  const gitLog = join(root, "git.log");
+  const cleanCount = join(root, "clean.count");
+
+  await mkdir(join(target, ".git"), { recursive: true });
+  await mkdir(join(target, "config"), { recursive: true });
+  await copyFile(join(repositoryRoot, "config", "p10k.zsh"), join(target, "config", "p10k.zsh"));
+  await copyFile(
+    join(repositoryRoot, "config", "hippo-memory-version"),
+    join(target, "config", "hippo-memory-version"),
+  );
+  await mkdir(bin, { recursive: true });
+
+  await writeFile(
+    join(bin, "pi"),
+    `#!/bin/sh
+count=0
+[ ! -f "$MOCK_PI_COUNT" ] || count=$(cat "$MOCK_PI_COUNT")
+count=$((count + 1))
+printf '%s\n' "$count" > "$MOCK_PI_COUNT"
+printf 'pi %s\n' "$*" >> "$MOCK_PI_LOG"
+if [ "$count" -eq 1 ]; then
+  if [ "$MOCK_CREATE_MARKER" = 1 ]; then
+    : > "$MOCK_MARKER"
+  fi
+  exit 1
+fi
+if [ "$MOCK_SECOND_PI_STATUS" -eq 0 ]; then
+  rm -f "$MOCK_MARKER"
+fi
+exit "$MOCK_SECOND_PI_STATUS"
+`,
+    "utf8",
+  );
+  await chmod(join(bin, "pi"), 0o755);
+
+  await writeFile(
+    join(bin, "git"),
+    `#!/bin/sh
+printf 'git %s\n' "$*" >> "$MOCK_GIT_LOG"
+case "$*" in
+  *" rev-parse --show-toplevel")
+    printf '%s\n' "$MOCK_GIT_TARGET"
+    ;;
+  *" remote get-url origin")
+    printf '%s\n' "$MOCK_GIT_ORIGIN"
+    ;;
+  *" clean -fdx")
+    count=0
+    [ ! -f "$MOCK_CLEAN_COUNT" ] || count=$(cat "$MOCK_CLEAN_COUNT")
+    count=$((count + 1))
+    printf '%s\n' "$count" > "$MOCK_CLEAN_COUNT"
+    if [ "$count" -eq 1 ]; then
+      printf '%s\n' 'warning: failed to remove node_modules/: Directory not empty' >&2
+      exit 1
+    fi
+    ;;
+esac
+`,
+    "utf8",
+  );
+  await chmod(join(bin, "git"), 0o755);
+
+  await writeFile(join(bin, "uname"), "#!/bin/sh\nprintf '%s\\n' Linux\n", "utf8");
+  await chmod(join(bin, "uname"), 0o755);
+
+  const env = {
+    ...process.env,
+    HOME: home,
+    XDG_CONFIG_HOME: join(home, ".config"),
+    PI_CODING_AGENT_DIR: agentDir,
+    MOCK_CREATE_MARKER: options.createMarker === false ? "0" : "1",
+    MOCK_MARKER: marker,
+    MOCK_PI_COUNT: piCount,
+    MOCK_PI_LOG: piLog,
+    MOCK_SECOND_PI_STATUS: String(options.secondPiStatus ?? 0),
+    MOCK_GIT_LOG: gitLog,
+    MOCK_CLEAN_COUNT: cleanCount,
+    MOCK_GIT_TARGET: target,
+    MOCK_GIT_ORIGIN: options.origin ?? "git@bitbucket.org:siakitem/my-pi.git",
+    PATH: `${bin}:${dirname(process.execPath)}:/usr/bin:/bin`,
+    ZSH: "",
+    ZSH_CUSTOM: "",
+    ZDOTDIR: home,
+  };
+  delete env.PI_PACKAGE_SOURCE;
+
+  return { cleanCount, env, gitLog, marker, piCount, piLog };
+}
+
+test("update.sh retries an identity-checked interrupted Git cleanup before retrying pi update", async (t) => {
+  const f = await fixture(t);
+  const result = spawnSync("sh", [join(repositoryRoot, "update.sh")], {
+    cwd: repositoryRoot,
+    env: f.env,
+    encoding: "utf8",
+    timeout: 30_000,
+  });
+
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  assert.equal((await readFile(f.piCount, "utf8")).trim(), "2");
+  assert.equal((await readFile(f.cleanCount, "utf8")).trim(), "2");
+  assert.match(result.stdout, /检测到默认组合包的 Pi Git 升级中断/);
+  assert.match(result.stdout, /第 2 次尝试后完成/);
+  await assert.rejects(readFile(f.marker, "utf8"), { code: "ENOENT" });
+});
+
+test("update.sh keeps the original fail-fast behavior when no update marker exists", async (t) => {
+  const f = await fixture(t, { createMarker: false });
+  const result = spawnSync("sh", [join(repositoryRoot, "update.sh")], {
+    cwd: repositoryRoot,
+    env: f.env,
+    encoding: "utf8",
+    timeout: 30_000,
+  });
+
+  assert.equal(result.status, 1);
+  assert.equal((await readFile(f.piCount, "utf8")).trim(), "1");
+  await assert.rejects(readFile(f.gitLog, "utf8"), { code: "ENOENT" });
+  assert.match(result.stderr, /pi update 执行失败/);
+});
+
+test("update.sh refuses cleanup when the cached checkout origin does not match", async (t) => {
+  const f = await fixture(t, { origin: "git@example.invalid:other/package.git" });
+  const result = spawnSync("sh", [join(repositoryRoot, "update.sh")], {
+    cwd: repositoryRoot,
+    env: f.env,
+    encoding: "utf8",
+    timeout: 30_000,
+  });
+
+  assert.equal(result.status, 1);
+  assert.equal((await readFile(f.piCount, "utf8")).trim(), "1");
+  const gitLog = await readFile(f.gitLog, "utf8");
+  assert.doesNotMatch(gitLog, /clean -fdx/);
+  assert.match(result.stderr, /checkout 身份校验失败/);
+});

update.sh

@@ -59,6 +59,49 @@ select_updated_bundle_config() {
 	fi
 }
 
+recover_incomplete_bundle_update() {
+	recovery_applicable=0
+	case $PACKAGE_SOURCE in
+		git:git@bitbucket.org:siakitem/my-pi.git) ;;
+		*) return 1 ;;
+	esac
+
+	agent_dir=${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}
+	recovery_target=$agent_dir/git/bitbucket.org/siakitem/my-pi
+	recovery_marker=$agent_dir/git/bitbucket.org/siakitem/.my-pi.pi-update-incomplete
+	if [ ! -f "$recovery_marker" ] || [ -L "$recovery_marker" ]; then
+		return 1
+	fi
+	if ! command -v git >/dev/null 2>&1 || [ ! -d "$recovery_target/.git" ]; then
+		warn "检测到 Pi Git 升级中断标记，但无法验证已安装 checkout，已跳过自动恢复。"
+		return 1
+	fi
+
+	recovery_target=$(CDPATH=; cd "$recovery_target" 2>/dev/null && pwd -P) || return 1
+	recovery_top=$(git -C "$recovery_target" rev-parse --show-toplevel 2>/dev/null) || return 1
+	recovery_top=$(CDPATH=; cd "$recovery_top" 2>/dev/null && pwd -P) || return 1
+	recovery_origin=$(git -C "$recovery_target" remote get-url origin 2>/dev/null) || return 1
+	if [ "$recovery_top" != "$recovery_target" ] || \
+		[ "$recovery_origin" != "git@bitbucket.org:siakitem/my-pi.git" ]; then
+		warn "检测到 Pi Git 升级中断标记，但 checkout 身份校验失败，拒绝自动清理。"
+		return 1
+	fi
+
+	recovery_applicable=1
+	say "检测到默认组合包的 Pi Git 升级中断，正在有限重试依赖清理。"
+	recovery_attempt=1
+	while [ "$recovery_attempt" -le 4 ]; do
+		if git -C "$recovery_target" clean -fdx; then
+			say "✓ Pi Git 缓存清理在第 ${recovery_attempt} 次尝试后完成。"
+			return 0
+		fi
+		warn "Pi Git 缓存第 ${recovery_attempt} 次清理未完成。"
+		recovery_attempt=$((recovery_attempt + 1))
+	done
+	warn "Pi Git 缓存清理在 4 次尝试后仍未完成；将交由最后一次 pi update 恢复依赖并报告结果。"
+	return 1
+}
+
 migrate_tool_search_settings() {
 	settings_file=${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/settings.json
 	if [ ! -e "$settings_file" ]; then
@@ -430,10 +473,28 @@ if ! command -v pi >/dev/null 2>&1; then
 fi
 
 say "正在升级 Pi 组合包：$PACKAGE_SOURCE"
-if ! pi update "$PACKAGE_SOURCE"; then
+if pi update "$PACKAGE_SOURCE"; then
+	:
+else
+	recovery_applicable=0
+	recovery_cleaned=0
+	if recover_incomplete_bundle_update; then
+		recovery_cleaned=1
+	fi
+	if [ "$recovery_applicable" -ne 1 ]; then
 		warn "pi update 执行失败，已停止后续升级。"
 		exit 1
 	fi
+	if [ "$recovery_cleaned" -eq 1 ]; then
+		say "正在重试 Pi 组合包升级，由 Pi 完成依赖安装并清除中断标记。"
+	else
+		warn "正在执行最后一次 pi update，以恢复可能被部分清理的依赖。"
+	fi
+	if ! pi update "$PACKAGE_SOURCE"; then
+		warn "pi update 自动恢复后仍然失败，已停止后续升级。"
+		exit 1
+	fi
+fi
 select_updated_bundle_config || exit 1
 migrate_tool_search_settings || record_update_failure "Tool Search 用户配置"