refactor: drive sync and remote-sync policy from provider capabilities (#1282)

Replaces four hard-coded agent switches in the sync engine and two hard-coded
Trae checks in remote sync with declarative provider capabilities.

`parser.Capabilities` gains a `Sync ProviderSyncSemantics` block declaring
per-provider cache and freshness policy: whether the fingerprint hash joins
the skip-cache key, whether freshness requires a stored-row hash match,
whether a skip-cache entry can be fresh before a stored row exists, and how
unchanged results from shared SQLite containers are dropped
(mtime vs mtime+hash). The engine reads these declarations instead of
switching on agent type; the deleted switch rationales move to the
declaration and consumption-site comments. `parser.AgentDef` gains
`RemoteSyncExcluded`, replacing the `def.Type == parser.AgentTrae` checks in
`internal/remotesync/resolve.go` and `internal/ssh/resolve.go`.

There is no behavior change: declarations reproduce the previous switch
memberships exactly, and a registry-wide parity test
(`TestProviderSyncSemanticsDeclarations`) asserts every registered agent's
declared semantics, including zero values for undeclared agents. One
removed code path — the `agent == ""` fallback in the cache-key helper — is
dead-code elimination: provider resolution by `file.Agent` precedes it and
fails first.

Why now: a pending Omnigent provider PR adds more consumers of both
capabilities; landing the refactor separately keeps that PR reviewable.

Reviewers should look at: `internal/parser/capabilities.go` (the new
types), `internal/sync/engine.go` (the four consumption sites), and
`internal/parser/capabilities_sync_test.go` (the parity table).


Co-authored-by: Wes McKinney <wesm@users.noreply.github.com>

Author: wesm

internal/parser/aider_provider.go

@@ -707,5 +707,8 @@ func aiderProviderCapabilities() Capabilities {
 			ToolResults:          CapabilitySupported,
 			PerMessageTokenUsage: CapabilitySupported,
 		},
+		Sync: ProviderSyncSemantics{
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
 	}
 }

internal/parser/capabilities.go

@@ -21,6 +21,28 @@ const (
 type Capabilities struct {
 	Source  SourceCapabilities
 	Content ContentCapabilities
+	Sync    ProviderSyncSemantics
+}
+
+// UnchangedResultPolicy controls how the engine compares parsed members from a
+// shared source with their stored rows. The zero value keeps every result.
+type UnchangedResultPolicy uint8
+
+const (
+	UnchangedResultNone UnchangedResultPolicy = iota
+	UnchangedResultMTime
+	UnchangedResultMTimeAndHash
+)
+
+// ProviderSyncSemantics declares stable provider-wide cache and result
+// freshness policy. Its zero value opts out of every specialized behavior.
+type ProviderSyncSemantics struct {
+	FingerprintHashInCacheKey           bool
+	FingerprintHashRequiredForFreshness bool
+	// SkipCacheFreshWithoutStoredRow permits a matching skip-cache entry to
+	// remain fresh before this provider has persisted a row for the source.
+	SkipCacheFreshWithoutStoredRow bool
+	UnchangedResults               UnchangedResultPolicy
 }
 
 // SourceCapabilities declares optional source mechanics implemented by a

internal/parser/capabilities_sync_test.go

@@ -0,0 +1,78 @@
+package parser
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+// TestProviderSyncSemanticsDeclarations verifies that every registered
+// provider's declared Capabilities().Sync matches the engine's historical
+// per-agent sync behavior. Providers not listed in wantSync are expected to
+// carry the zero-value ProviderSyncSemantics.
+func TestProviderSyncSemanticsDeclarations(t *testing.T) {
+	wantSync := map[AgentType]ProviderSyncSemantics{
+		AgentClaude: {
+			FingerprintHashInCacheKey:           true,
+			FingerprintHashRequiredForFreshness: true,
+			SkipCacheFreshWithoutStoredRow:      true,
+		},
+		AgentCodex: {
+			FingerprintHashInCacheKey:           true,
+			FingerprintHashRequiredForFreshness: true,
+			SkipCacheFreshWithoutStoredRow:      true,
+		},
+		AgentDevin: {
+			FingerprintHashInCacheKey:           true,
+			FingerprintHashRequiredForFreshness: true,
+		},
+		AgentQoder: {
+			FingerprintHashInCacheKey:           true,
+			FingerprintHashRequiredForFreshness: true,
+		},
+		AgentWindsurf: {
+			FingerprintHashInCacheKey:           true,
+			FingerprintHashRequiredForFreshness: true,
+		},
+		AgentHermes: {
+			FingerprintHashRequiredForFreshness: true,
+		},
+		AgentGemini: {
+			FingerprintHashRequiredForFreshness: true,
+		},
+		AgentZed: {
+			UnchangedResults: UnchangedResultMTime,
+		},
+		AgentKiro: {
+			UnchangedResults: UnchangedResultMTime,
+		},
+		AgentTrae: {
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
+		AgentAider: {
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
+		AgentShelley: {
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
+		AgentOpenCode: {
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
+		AgentKilo: {
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
+		AgentMiMoCode: {
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
+		AgentIcodemate: {
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
+	}
+
+	for _, factory := range ProviderFactories() {
+		agent := factory.Definition().Type
+		t.Run(string(agent), func(t *testing.T) {
+			assert.Equal(t, wantSync[agent], factory.Capabilities().Sync)
+		})
+	}
+}

internal/parser/claude_provider.go

@@ -649,5 +649,10 @@ func claudeProviderCapabilities() Capabilities {
 			Model:                CapabilitySupported,
 			StopReason:           CapabilitySupported,
 		},
+		Sync: ProviderSyncSemantics{
+			FingerprintHashInCacheKey:           true,
+			FingerprintHashRequiredForFreshness: true,
+			SkipCacheFreshWithoutStoredRow:      true,
+		},
 	}
 }

internal/parser/codex_provider.go

@@ -836,5 +836,10 @@ func codexProviderCapabilities() Capabilities {
 			TerminationStatus:    CapabilitySupported,
 			Model:                CapabilitySupported,
 		},
+		Sync: ProviderSyncSemantics{
+			FingerprintHashInCacheKey:           true,
+			FingerprintHashRequiredForFreshness: true,
+			SkipCacheFreshWithoutStoredRow:      true,
+		},
 	}
 }

internal/parser/devin_provider.go

@@ -642,5 +642,9 @@ func devinProviderCapabilities() Capabilities {
 			PerMessageTokenUsage: CapabilitySupported,
 			Model:                CapabilitySupported,
 		},
+		Sync: ProviderSyncSemantics{
+			FingerprintHashInCacheKey:           true,
+			FingerprintHashRequiredForFreshness: true,
+		},
 	}
 }

internal/parser/gemini_provider.go

@@ -649,5 +649,8 @@ func geminiProviderCapabilities() Capabilities {
 			PerMessageTokenUsage: CapabilitySupported,
 			Model:                CapabilitySupported,
 		},
+		Sync: ProviderSyncSemantics{
+			FingerprintHashRequiredForFreshness: true,
+		},
 	}
 }

internal/parser/hermes_provider.go

@@ -1592,5 +1592,8 @@ func hermesProviderCapabilities() Capabilities {
 			AggregateUsageEvents: CapabilitySupported,
 			Model:                CapabilitySupported,
 		},
+		Sync: ProviderSyncSemantics{
+			FingerprintHashRequiredForFreshness: true,
+		},
 	}
 }

internal/parser/kiro_provider.go

@@ -787,5 +787,8 @@ func kiroProviderCapabilities() Capabilities {
 			ToolCalls:    CapabilitySupported,
 			ToolResults:  CapabilitySupported,
 		},
+		Sync: ProviderSyncSemantics{
+			UnchangedResults: UnchangedResultMTime,
+		},
 	}
 }

internal/parser/opencode_provider.go

@@ -736,8 +736,8 @@ func (s openCodeFormatSourceSet) Fingerprint(
 		return SourceFingerprint{}, fmt.Errorf("stat %s: source is a directory", path)
 	}
 	fingerprint.Size = info.Size()
-	// No content hash: no engine freshness gate consumes it for this
-	// family (see providerFingerprintHashRequiredForFreshness), and the
+	// No content hash: this family declares FingerprintHashRequiredForFreshness
+	// false, so no engine freshness gate consumes it, and the
 	// authoritative storage fingerprint is computed by Parse and compared
 	// post-parse by dropUnchangedSharedSQLiteResults. Computing it here
 	// re-read and re-hashed every message and part file of the session on
@@ -1126,5 +1126,8 @@ func openCodeFormatProviderCapabilities() Capabilities {
 			PerMessageTokenUsage: CapabilitySupported,
 			Model:                CapabilitySupported,
 		},
+		Sync: ProviderSyncSemantics{
+			UnchangedResults: UnchangedResultMTimeAndHash,
+		},
 	}
 }