feat(data-layout): auto-migrate a legacy .teamai into the partition (#374 P1-3)

[jeff-r2026]

What & why

P1-3 of issue #374. Earlier P1 PRs (#397/#402/#406/#414/#417) routed new
installs' machine data to the per-project partition ~/.teamai/projects/<slug>/
and read old installs via a legacy fallback. This PR is the final piece: it
automatically migrates a real legacy <repo>/.teamai/ into the partition on
the first write command, so an upgraded project ends up with zero teamai
residue in its workspace.

How it works

Trigger — the global preAction hook (src/index.ts), narrowed twice:

• only init / pull / push (read-only commands keep using the double-read fallback);
• hook-dispatch excluded via TEAMAI_HOOK_SUBCOMMANDS (a high-frequency silent path must never move 12 MB);
• --dry-run previews without writing.

Gate (planMigration, deliberately not detectProjectConfig — that
short-circuits on an existing partition and runs the self-heal bootstrap, both of
which would mask the raw legacy state): act iff git repo + legacy config.yaml
exists + scope: project + kind != self. self mode is a hard no-op — its
.teamai/ is team knowledge committed to main.

Steps (runMigration) — copy → verify → atomic rename, holding
<legacyDir>/.sync-lock (the exact lock an un-migrated pull/push contends on)
across the whole window:

1. copy legacyDir → <partition>.staging with raw fse.copy, not copyDir (copyDir filters out .git and would corrupt the team-repo clone); skip disposable worktrees + lock files;
2. verify staging (config parses; team-repo git rev-parse HEAD works; every entry present);
3. rebase repo.localPath (was <legacyDir>/team-repo) onto the partition;
4. atomic rename(staging → partition);
5. write the anchor reverse-lookup file (the slug is a one-way sha256);
6. release the lock, then retire legacyDir → .teamai.bak/ (never auto-deleted — the manual rollback path).

Interrupt recovery — a crash before step 4 leaves the partition absent and the
source intact (discard .staging/, retry). A crash between the partition rename
and the source retire is finished by the next write command's retire-only plan
(retire the lingering legacy dir without re-copying onto the authoritative
partition), so the legacy dir — incl. its plaintext env — never lingers forever.

Downgrade is not supported — flagged in the design doc and the bilingual usage
guides, which also correct the now-stale <cwd>/.teamai layout to the partition.

Test Plan

Unit (src/__tests__/migrate.test.ts, 19 tests) — all green

Builds a real legacy layout (real git anchors + a real nested git clone), not
an empty fixture. Covers: every plan gate (non-git / user-scope / self / malformed
/ partition-exists→retire-only); .git survival; repo.localPath rebase (inside
vs. outside legacyDir); lock not buried in backup; disposable worktrees skipped;
idempotence; retire-only finishes an interrupted run without overwriting the
partition; corrupt staged clone aborts, source untouched, no partition/.bak/
.staging; http-mode install migrates; leftover-staging recovery; dry-run
no-op.

Full suite

npx tsc --noEmit clean · npm run build OK · npx vitest run → 2747 passed.

Real-CLI end-to-end (built dist/index.js, isolated HOME + real git repos)

Scenario	Result
--dry-run pull	✅ partition not created, legacy untouched, no .bak
real pull migrates	✅ config/state/index/env/managed-mcp → partition; anchor written; team-repo/.git survives, HEAD matches, git status works
repo.localPath rebased	✅ names <partition>/team-repo (resolves to a usable clone), no longer the legacy path
workspace residue	✅ legacy .teamai gone; .teamai.bak/ kept with old config; no live .sync-lock in backup
idempotent second pull	✅ no re-migration, no legacy re-created
push triggers migration	✅
status (read-only)	✅ does not migrate
hook-dispatch	✅ does not migrate
self mode	✅ no-op — partition not created, committed knowledge untouched, no .bak
interrupted-state recovery (partition built + legacy lingering)	✅ next pull retires the leftover legacy, moves plaintext env out of the workspace, partition not overwritten

Docs

docs/designs/data-directory-layout.md (P1 marked implemented + full migration
section) and bilingual docs/usage-guide{,.zh-CN}.md (partition layout + upgrade/
migration note + downgrade warning) updated.

Out of scope (per issue)

teamai migrate/gc/--revert commands; cross-project shared clone; P2 (self
slimming); P3 (constant functionization + status --all).

[jeff-r2026]

两个问题都已本地复现并修复(commit 8f07b02),各配了真实回归测试。

1. [P1] 自动迁移永久删除已有备份
成立。retireLegacy 在 rename 前无条件 remove(backup),已有的 .teamai.bak/(上次迁移留下的或用户自己的)会被删除,普通 teamai pull 升级即造成不可恢复的数据丢失。
修复:绝不删除已有备份,改为选第一个空闲名——.teamai.bak,已存在则 .teamai.bak.1、.teamai.bak.2…

2. [P1] 备份改名可能让凭据进入 Git 提交
成立,且已复现:老装的 .teamai/ 仅靠仓库根 .gitignore 的 .teamai/ 规则保护,该规则不匹配 .teamai.bak/,迁移后 git add -A + git show :.teamai.bak/env 能读出明文凭据。
修复:改名前先在源目录内写一个自包含的 .gitignore(内容 *),使备份无论最终叫什么名字、无论仓库用哪种忽略写法,都忽略自身全部内容——不存在「凭据短暂落在未忽略目录」的窗口。

验证(真实 CLI,dist/index.js):

• 已有 .teamai.bak/only-copy.txt 迁移后保留,本次备份落 .teamai.bak.1,partition 正确,工作区零残留
• 迁移后 git add -A 下 .teamai.bak 无任何文件被暂存;git show :.teamai.bak/env 与 :.teamai.bak/token 均失败;备份文件仍在磁盘上(回滚路径完好)
• 三种仓库根忽略写法(.teamai/、/.teamai/、.teamai)均通过

回归测试新增 2 个:「never overwrites an existing .teamai.bak」「keeps the retired backup git-ignored so a git add -A cannot leak its secrets」。全量单测 2749 passed,tsc / build 均通过。design 文档的 retire 步骤已同步这两项安全措施。