Skip to content

fix: prevent silent capability loss for users upgrading from old versions - #311

Merged
jeff-r2026 merged 1 commit into
Tencent:mainfrom
m0Nst3r873:fix/upgrade-capability-loss
Aug 24, 2026
Merged

fix: prevent silent capability loss for users upgrading from old versions#311
jeff-r2026 merged 1 commit into
Tencent:mainfrom
m0Nst3r873:fix/upgrade-capability-loss

Conversation

@m0Nst3r873

Copy link
Copy Markdown
Collaborator

Summary

A user on v0.20.0 reported the project-binding prompt never appearing. Root-cause investigation traced it to a class of upgrade-migration defects: a runtime capability depends on a file/field/structure that only a newer version's write path produces, but upgrading neither backfills it nor self-heals — so users who initialized on an old version are silently degraded after upgrade, with nothing in the logs.

This PR fixes the four instances of that class that exist on main:

Area Fix
local-agent config backfill loadLocalAgentConfig now backfills a missing ~/.teamai/local-agent/config.json from the legacy ~/.teamai/config.yaml (http repo) + ~/.teamai/apikey, and auto-provisions it. v0.17.x upgraders (who initialized before the local-agent module existed) regain the binding prompt + resource sync without re-running init. The write is guarded so a persist failure degrades to an in-memory config instead of throwing out of the hook path.
binding cleanup The legacy groupId-only binding cleanup is now persisted once and warns the user once, instead of re-firing the warning on every hook load and never self-completing.
recall / team-codebase The recall fallback rebuild stops indexing the retired docs/team-codebase (aligning with pull.ts, which already dropped it for the teamwiki graph engine) and warns users to migrate to teamwiki/. Previously the two index-build paths diverged, so old teams' codebase knowledge silently vanished from most recalls.
graph-index version guard loadGraphIndex now rejects an index whose schemaVersion does not match GRAPH_INDEX_SCHEMA_VERSION (returns null → rebuild), mirroring the existing search-index SEARCH_INDEX_VERSION + isLegacyIndex self-heal.

Note on scope

Two further instances of the same defect class (a scope-asymmetric gitOnly hook filter, and self-mode bootstrap not triggering for pre-existing project configs) live only on the beta/0.20.0-beta.8 branch, not on main, so they are out of scope here and should be addressed when that branch merges to main.

Test Plan

  • npx tsc --noEmit — clean
  • npm run build — success
  • npx vitest run1824 passed (146 files)
  • Updated the issue [bug] codebase 图谱检索多处缺陷(不递归/camelCase 失效/全局图被覆盖/tokenizer 不一致) #84 loadGraphIndex regression test for the new schemaVersion guard, plus a new case asserting a mismatched version returns null
  • E2E (isolated HOME): legacy config.yaml (kind=http) + apikey with no local-agent/config.jsonloadLocalAgentConfig() returns the backfilled endpoint+token and auto-writes config.json; no false backfill when neither legacy config nor env endpoint is present
  • E2E (isolated HOME): real recall() over a repo containing docs/team-codebase/ emits the migration warning and no longer indexes it

🤖 Generated with Claude Code

…ions

Four upgrade-migration defects where a runtime capability depended on a
file/field/structure that only a newer version produces, with no backfill
or self-heal on upgrade — leaving upgraders silently degraded:

- local-agent: when local-agent/config.json is missing (v0.17.x users
  upgrading from the pre-local-agent era), backfill it from the legacy
  ~/.teamai/config.yaml (http repo) plus ~/.teamai/apikey and auto-provision
  it, so the project-binding prompt and resource sync are not lost. The save
  is wrapped so a write failure degrades to an in-memory config instead of
  throwing out of the hook path.
- local-agent: persist the legacy group-based binding cleanup and warn the
  user once, instead of re-firing the warning on every hook load.
- recall: stop indexing the retired docs/team-codebase in the fallback
  rebuild (aligning with pull.ts) and warn users to migrate to teamwiki/.
- graph-index: guard loadGraphIndex on schemaVersion so a legacy/mismatched
  index returns null and triggers a rebuild instead of loading silently.

Update the issue Tencent#84 regression test for the new schemaVersion guard and add
a case asserting a mismatched version returns null.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@jeff-r2026
jeff-r2026 self-requested a review August 24, 2026 09:15
@jeff-r2026
jeff-r2026 merged commit e81be18 into Tencent:main Aug 24, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants