refactor(migration): make migrations user-invoked via 'amplifier-agent migrate'#52
Merged
Merged
Conversation
…t migrate' Removed automatic invocation of storage migrations from the engine boot path and update command. Both migrations (flat sessions → workspaces, XDG → ~/.amplifier-agent) are idempotent one-shot operations that provided minimal value via auto-execution. User feedback: migration logs are annoying during normal use. Making migrations explicitly invoked via 'amplifier-agent migrate' subcommand improves the UX. Changes: - Removed migrate_legacy_sessions_if_needed() call from _runtime.py handler() - Removed maybe_migrate_legacy_xdg_storage() call from update.py - Added 'amplifier-agent migrate' subcommand (admin/migrate.py) - Wired subcommand into CLI (__main__.py) - Updated migration.py docstring to reflect user-invoked contract - Inverted assertions in test_runtime_migration_wired.py (now tests NOT called) - Added comprehensive test suite test_admin_migrate.py (15 tests) - Appended 'Amendment' section to design doc documenting follow-up Both migrations remain idempotent and safe to re-run. Subsequent invocations report skipped=True. Wrapper-facing contracts unchanged. Test results: 710 pass; pre-existing integration failures unrelated. Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
This was referenced Jun 12, 2026
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
1 participant
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.
Motivation
Two storage migrations were auto-running on every engine boot and update, producing log noise:
_runtime.py:286amplifier-agent updateviaupdate.py:300Both migrations are idempotent one-shot operations — auto-execution provided little value beyond the first invocation. Making them explicitly user-invoked via
amplifier-agent migratesubcommand improves the UX.What changed
Removed auto-invocation sites:
src/amplifier_agent_lib/_runtime.py: Removed import,_MIGRATION_RANguard, andmigrate_legacy_sessions_if_needed()call fromhandler()src/amplifier_agent_cli/admin/update.py: Removed import and entire migration call block from thereturncode == 0pathAdded standalone subcommand:
src/amplifier_agent_cli/admin/migrate.py(NEW):amplifier-agent migrateClick command that calls both migrations in sequence, supports--output {text,json}src/amplifier_agent_cli/__main__.py: Wired subcommand into CLIUpdated documentation:
src/amplifier_agent_lib/migration.pydocstring: Functions now user-invoked, not auto-rundocs/designs/2026-06-11-drop-xdg-and-flag-cleanup.md: Appended "Amendment — Migration Auto-Invocation Removed" sectionTest changes:
tests/test_runtime_migration_wired.py: Inverted assertions (now tests NOT called on boot)tests/cli/test_admin_migrate.py(NEW): 15 tests covering migration invocation, idempotency, JSON output, exit codes, CLI wiringMigration UX after this PR
amplifier-agent migratewhen readyamplifier-agent migratewhen readyBoth migrations remain idempotent and safe to re-run. Subsequent calls report
skipped=True.Wrapper contract preservation
No wrapper-facing surface changed. Wrappers never relied on auto-migration. No flag changes, no envelope shape changes, no exit code changes.
Test results
710 tests pass.
Pre-existing integration failures (
test_audit_e2e,test_workspace_e2e,test_migration_e2e) reference a--providerflag and predate this branch — unrelated to this change.Companion
Companion to the design doc at
docs/designs/2026-06-11-drop-xdg-and-flag-cleanup.md(which now has an amendment section noting this follow-up).