fix: prevent silent capability loss for users upgrading from old versions - #311
Merged
Merged
Conversation
…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
self-requested a review
August 24, 2026 09:15
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:loadLocalAgentConfignow backfills a missing~/.teamai/local-agent/config.jsonfrom 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-runninginit. The write is guarded so a persist failure degrades to an in-memory config instead of throwing out of the hook path.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.docs/team-codebase(aligning withpull.ts, which already dropped it for the teamwiki graph engine) and warns users to migrate toteamwiki/. Previously the two index-build paths diverged, so old teams' codebase knowledge silently vanished from most recalls.loadGraphIndexnow rejects an index whoseschemaVersiondoes not matchGRAPH_INDEX_SCHEMA_VERSION(returns null → rebuild), mirroring the existing search-indexSEARCH_INDEX_VERSION+isLegacyIndexself-heal.Note on scope
Two further instances of the same defect class (a scope-asymmetric
gitOnlyhook filter, and self-mode bootstrap not triggering for pre-existing project configs) live only on thebeta/0.20.0-beta.8branch, not onmain, so they are out of scope here and should be addressed when that branch merges tomain.Test Plan
npx tsc --noEmit— cleannpm run build— successnpx vitest run— 1824 passed (146 files)loadGraphIndexregression test for the newschemaVersionguard, plus a new case asserting a mismatched version returns nullconfig.yaml(kind=http) +apikeywith nolocal-agent/config.json→loadLocalAgentConfig()returns the backfilled endpoint+token and auto-writesconfig.json; no false backfill when neither legacy config nor env endpoint is presentrecall()over a repo containingdocs/team-codebase/emits the migration warning and no longer indexes it🤖 Generated with Claude Code