fix: detect newer session database and show clear upgrade message

Add a pre-flight check in InitializeMigrations that compares the highest
migration ID in the database against what the binary knows. If the database
was created by a newer version, return a clear error with the current
docker-agent version and a prompt to upgrade, instead of letting the user
hit cryptic SQL errors like 'no such column'.

Skip the backup-and-recovery path for this error to avoid silently
destroying the user's session data.

Assisted-By: docker-agent

Author: dgageot

pkg/session/migrations.go

@@ -10,6 +10,8 @@ import (
 	"time"
 
 	"github.com/google/uuid"
+
+	"github.com/docker/docker-agent/pkg/version"
 )
 
 // Migration represents a database migration
@@ -42,6 +44,11 @@ func (m *MigrationManager) InitializeMigrations(ctx context.Context) error {
 		return fmt.Errorf("failed to create migrations table: %w", err)
 	}
 
+	// Check if the database was created by a newer version of the application
+	if err := m.checkForUnknownMigrations(ctx); err != nil {
+		return err
+	}
+
 	// Run all pending migrations
 	err = m.RunPendingMigrations(ctx)
 	if err != nil {
@@ -64,6 +71,30 @@ func (m *MigrationManager) createMigrationsTable(ctx context.Context) error {
 	return err
 }
 
+// checkForUnknownMigrations checks if the database has migrations that this binary
+// doesn't know about, which indicates the database was created by a newer version.
+// This produces a clear error instead of cryptic SQL failures from schema mismatches.
+func (m *MigrationManager) checkForUnknownMigrations(ctx context.Context) error {
+	known := getAllMigrations()
+	maxKnownID := known[len(known)-1].ID
+
+	var maxAppliedID int
+	err := m.db.QueryRowContext(ctx, "SELECT COALESCE(MAX(id), 0) FROM migrations").Scan(&maxAppliedID)
+	if err != nil {
+		return fmt.Errorf("failed to check applied migrations: %w", err)
+	}
+
+	if maxAppliedID > maxKnownID {
+		return fmt.Errorf(
+			"%w: you are running docker-agent %s which supports migrations up to %d, "+
+				"but the session database has migration %d from a newer version; "+
+				"please upgrade docker-agent to the latest version",
+			ErrNewerDatabase, version.Version, maxKnownID, maxAppliedID)
+	}
+
+	return nil
+}
+
 // RunPendingMigrations executes all migrations that haven't been applied yet
 func (m *MigrationManager) RunPendingMigrations(ctx context.Context) error {
 	migrations := getAllMigrations()

pkg/session/store.go

@@ -19,8 +19,9 @@ import (
 )
 
 var (
-	ErrEmptyID  = errors.New("session ID cannot be empty")
-	ErrNotFound = errors.New("session not found")
+	ErrEmptyID       = errors.New("session ID cannot be empty")
+	ErrNotFound      = errors.New("session not found")
+	ErrNewerDatabase = errors.New("session database was created by a newer version of docker-agent")
 )
 
 // parseRelativeSessionRef checks if ref is a relative session reference (e.g., "-1", "-2")
@@ -367,6 +368,12 @@ func (s *InMemorySessionStore) Close() error {
 func NewSQLiteSessionStore(path string) (Store, error) {
 	store, err := openAndMigrateSQLiteStore(path)
 	if err != nil {
+		// Don't attempt recovery for version mismatch - the user needs to upgrade,
+		// not silently lose their data by starting fresh.
+		if errors.Is(err, ErrNewerDatabase) {
+			return nil, err
+		}
+
 		// If migrations failed, try to recover by backing up the database and starting fresh
 		slog.Warn("Failed to open session store, attempting recovery", "error", err)
 

pkg/session/store_test.go

@@ -629,6 +629,32 @@ func TestAgentModelOverrides_EmptyMap(t *testing.T) {
 	assert.Empty(t, retrieved.AgentModelOverrides)
 }
 
+func TestNewSQLiteSessionStore_RejectsNewerDatabase(t *testing.T) {
+	tempDir := t.TempDir()
+	dbPath := filepath.Join(tempDir, "test_newer_db.db")
+
+	// Create a valid store first (applies all known migrations)
+	store, err := NewSQLiteSessionStore(dbPath)
+	require.NoError(t, err)
+	defer store.(*SQLiteSessionStore).Close()
+
+	// Inject a future migration into the database to simulate a newer version
+	db, err := sql.Open("sqlite", dbPath)
+	require.NoError(t, err)
+	_, err = db.Exec(
+		"INSERT INTO migrations (id, name, description, applied_at) VALUES (?, ?, ?, ?)",
+		9999, "9999_future_migration", "Added by a newer version", "2099-01-01T00:00:00Z")
+	require.NoError(t, err)
+	db.Close()
+
+	// Opening the store should fail with a clear error about version mismatch
+	_, err = NewSQLiteSessionStore(dbPath)
+	require.Error(t, err)
+	require.ErrorIs(t, err, ErrNewerDatabase)
+	assert.Contains(t, err.Error(), "9999")
+	assert.Contains(t, err.Error(), "upgrade docker-agent")
+}
+
 func TestNewSQLiteSessionStore_MigrationFailureRecovery(t *testing.T) {
 	tempDir := t.TempDir()
 	dbPath := filepath.Join(tempDir, "test_migration_recovery.db")