feat(migrate): retain unsupported v0 resources automatically

[notgitika]

Description

Follow-up to #2584 (agentcore migrate). It preserves v0 resources that v1 does not manage, while keeping capacity-provider migrations blocked until v1 supports them.

Retained outside the v1 stack

Migrate now handles these resources the same way:

• datasets
• knowledge bases
• insights-only online evaluation configs

They are removed from the migrated agentcore.json. Before the stack refactor, migrate sets DeletionPolicy and UpdateReplacePolicy to Retain on each resource and its dropped supporting resources. The first v1 deploy removes them from the stack while leaving them in AWS.

The retained-resource traversal follows CloudFormation references in both directions. This keeps resources that the retained resource depends on and resources that point back to it, such as an AWS::IAM::Policy attached to a knowledge base service role.

Capacity providers and runtimes that use them remain migration blockers.

References from resources that remain in v1

Knowledge-base gateway connector references cannot keep using a removed project knowledge-base name. Migrate now:

• rewrites Retrieve and AgenticRetrieveStream references to the unique deployed knowledge-base ID and shows the rewrite in the preview; or
• blocks migration at the exact field when no unique valid deployed ID is available.

This prevents the migrated project from retaining a dangling reference.

Retain change-set recovery

• A failure to create the retain change set no longer reports a change-set ID that was never created.
• Successfully completed retain change sets are cleaned up on the normal path.
• A successful rerun also cleans up a retain change set recorded by an earlier unknown-outcome run, including migrations that ultimately require no stack refactor.

Other output behavior

• Unsupported blockers are summarized once; their resource-level details remain in the full preview.
• No message tells users to delete resources.
• Missing/old/local CDK library and customized CDK app diagnostics remain actionable.
• The apply hint preserves --target.

Related Issue

No public issue yet; follows up #2584.

Documentation PR

The user-facing migration guide is in progress separately.

How to test

agentcore migrate currently needs the @aws/agentcore-cdk support from aws/agentcore-l3-cdk-constructs#423. Point AGENTCORE_MIGRATE_CDK_LIBRARY at a build of that PR, then use a clean, committed v0 project containing the resources above.

1. Run agentcore migrate without applying and inspect both the terminal preview and agentcore/.cli/migrate/plan-<timestamp>.md.
2. Confirm knowledge bases, datasets, and insights-only online evals are listed as retained, while capacity providers still block.
3. For a KB connector using a project KB name, confirm the preview shows its rewrite to the deployed ID. Remove or conflict the recorded ID and confirm migration blocks at that connector field instead.
4. Apply with agentcore migrate --yes, then deploy v1. The retained resources should leave the stack with DELETE_SKIPPED and remain in AWS.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Testing

• bun test — 4489 pass, 0 fail
• bun run typecheck
• bun run lint:check
• bun run format:check
• bun run build
• Relevant migrate planning, conversion, retain, recovery, contract, and handler tests

Checklist

• I have added tests proving the changed behavior.
• The change generates no new warnings.
• The dependent CDK change has been merged and published (aws/agentcore-l3-cdk-constructs#423 is pending).

---

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: Looks good

The retain-before-refactor machinery is thoughtful and well-tested. Highlights:

• retainResources is defensive at every step: it verifies the change set contains only the two retain-policy attribute changes on exactly the expected resources (retainChangesMismatch), deletes a mismatched set unexecuted, distinguishes CloudFormation refusal (execute-failed, stack unchanged) from a lost response (unknown, needs-repair), and re-reads the deployed template after UPDATE_COMPLETE to confirm the policies really landed before letting the refactor proceed.
• Journal/rerun semantics are correct. retaining isn't a resumable state — on rerun, plan re-reads the deployed template and resourcesToRetain sees alreadyRetained=true for anything the earlier attempt actually persisted, so retain collapses to undefined and no duplicate update is attempted. New change set names are timestamp-unique, so leftovers from an unknown-outcome run don't collide.
• repairSteps correctly uses retainChangeSet && !refactorId to pick the retain-specific recovery message, and that message correctly notes the update only touched DeletionPolicy/UpdateReplacePolicy and nothing was deleted or replaced.
• Tests mock only at the CFN SDK boundary (fakeCloudFormation) and use temp dirs for FS — in line with the project's testing patterns.

A couple of very minor things noticed but not worth blocking on:

• In retain.ts, the create-failed branch sets details.refactorId: changeSetName on StackRefactorError even though onCreated wasn't called and no change set exists in AWS. Harmless (apply.ts only uses error.message), but slightly misleading if that detail is ever surfaced elsewhere.
• An unknown-outcome retain that in reality succeeded leaves the executed change set on the stack after a successful rerun (the rerun creates a fresh one). Minor clutter, not a correctness problem.

Nothing requiring changes before merge.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.65145% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.54%. Comparing base (759924e) to head (b40173b).
⚠️ Report is 2 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/core/project/migrate/retain.ts	94.05%	16 Missing ⚠️
src/core/project/migrate/replacements.ts	66.66%	4 Missing ⚠️
src/core/project/migrate/apply.ts	97.29%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2598      +/-   ##
============================================
- Coverage     96.55%   96.54%   -0.01%     
============================================
  Files           697      698       +1     
  Lines         56670    57246     +576     
============================================
+ Hits          54715    55271     +556     
- Misses         1955     1975      +20     

☔ 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)

[jariy17]

It looks good. Just a small non blocking fix.

[jariy17]

Can we check (config.insights?.length ?? 0) > 0 here?

For example, an evaluator config can have:

{
  "evaluators": ["Builtin.Helpfulness"],
  "insights": []
}

This config uses an evaluator and has no insights. The current check treats it as insights-only because the field exists, so migration removes it from onlineEvalConfigs. It should stay in the migrated project.