feat(compat): fail when project version and CDK library disagree

[notgitika]

Description

Fails loudly when a project's format and its vended CDK library disagree, for example when someone changes "version" in agentcore.json by hand.

• Format comes from agentcore.json version (1 is v0, otherwise v1). Library comes from @aws/agentcore-cdk in agentcore/cdk/package.json: major 0 (0.1.0-alpha.*) is v0, major 1+ (including 1.0.0-rc.*/-preview.*) is v1.
• On a mismatch, project resolution throws ProjectStateError:
  • "agentcore/agentcore.json says this is a v1 project (version 2), but its CDK library is v0 (@aws/agentcore-cdk …). Set "version" back to 1, or run agentcore migrate to upgrade it."
  • "agentcore/agentcore.json says this is a v0 project (version 1), but its CDK library is v1 (@aws/agentcore-cdk …). Set "version" to 2, or reinstall the v0 CDK app."
• A missing or unreadable package.json, no such dependency, or a spec that isn't plain semver (file:, workspace:, git URLs, ranges) never blocks.
• Reuses the package.json read from fix(project): guide outdated v0 projects to update dependencies #2566. Outdated v0 projects still get its "older than v0.24.2" guidance first.

One #2566 test (version: 2 with an 0.1.0-alpha library loads fine) is replaced, since that combination is now the mismatch error.

Builds on #2575, which is now merged.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

• I ran bun test
• End-to-end tests are not applicable: project resolution is local and read-only (4144 passed)
• I ran bun run typecheck
• I ran bun run lint:check
• I ran bun run format:check

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Changes requested

Nice, focused change with thorough table-driven tests covering ranges, prereleases, invalid specs, missing/malformed manifests, and no-op side effects. One small issue:

Broken JSDoc comment above MODEL_PROVIDER_RUNTIMES_CN_MESSAGE

src/core/project/manager.tsx lines 155–162: inserting assertCdkLibraryMatches left a stray blank line inside the next JSDoc block:

}

/**

 * Shown when a runtime template hardwired to an unreachable model provider
 ...
 */
export const MODEL_PROVIDER_RUNTIMES_CN_MESSAGE = ...

The /** line is now followed by a blank line before the *-prefixed description. Compare the parent commit (e7162595) where it was a normal JSDoc block. Please remove the blank line so the comment reads as intended.

Non-blocking observations

• declaredCdkDependency is now called on every resolve() call (previously only on the v0 fallback). The extra package.json read is cheap and swallowed via .catch(() => undefined), so this is fine — just flagging the behavior change.
• No telemetry is emitted for the new mismatch error, but the existing adjacent ProjectStateError paths (v0 dependency warning, legacy write-gate) also don't emit, so this is consistent with surrounding code.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.32%. Comparing base (c901a82) to head (9e5471f).

Additional details and impacted files

@@            Coverage Diff            @@
##           refactor    #2578   +/-   ##
=========================================
  Coverage     96.32%   96.32%           
=========================================
  Files           670      670           
  Lines         51173    51197   +24     
=========================================
+ Hits          49290    49314   +24     
  Misses         1883     1883           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)