fix(controller): skip DB migration when DB schema is ahead of binary

[onematchfox]

When an older binary starts against a database that a newer binary has already migrated, calling mg.Up() fails because golang-migrate tries to read the down file for the current DB version, which does not exist in the older binary's embedded FS. This results in the controller crash looping (issue #1881).

Instead, detect when the database version exceeds the binary's highest known migration and return early. This relies on the expand-then-contract policy documented in database-migrations.md, which guarantees each release's code is compatible with the schema applied by the previous release.

Adds TestApplyDir_SucceedsWhenDBVersionAhead to cover this path.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR makes the migration runner tolerant of running an older binary against a database schema migrated by a newer binary, avoiding crash-loops by skipping migration application when the DB version is ahead of the binary’s embedded migrations.

Changes:

• Add a “compatibility mode” early-return in applyDir when DB schema version exceeds the binary’s max embedded migration version.
• Introduce maxEmbeddedVersion to compute the highest embedded migration version from the filesystem.
• Add a regression test ensuring applyDir succeeds (and does not modify schema version) when the DB version is ahead.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
go/core/pkg/migrations/runner.go	Adds compatibility-mode logic and a helper to scan embedded migrations for the max version.
go/core/pkg/migrations/runner_test.go	Adds a test proving older binaries don’t error or roll back when DB schema is ahead.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

[iplay88keys]

This might be changed when we update the db migration/rollback logic, but this is a good incremental improvement in the meantime.

Thinking more about this so we don't introduce a footgun here.

[iplay88keys]

Sorry for un-approving this PR. I want to make sure the implications of this change are well thought through.

Let's start with aligning on a few things:

• We only support n+1 upgrades and n-1 downgrades.
• We also don't currently have a guarantee that a downgrade doesn't require manual steps, but we try to avoid them on upgrades.

The current db migrations are set up such that the application fails to start if there are more migrations applied to the db than the binary knows about. This is by design to prevent data corruption.

There is no way for the binary to know what migrations are in n+1 vs n+2 without going back and editing the old artifacts or making this incompatible with airgapped environments.

This PR removes the aforementioned check (comparing known migrations vs what's migrated), effectively introducing a requirement that Kagent stays compatible with future database schema shape changes and queries. It also leaves a subtle footgun as the information regarding the "compatibility mode" is only surfaced in a log line.

Even with this change, there is still a manual database rollback requirement in order to not be in an inconsistent state. So I'm not sure that it's worth taking on these additional support burdens in that case.