feat(parse-diff): cover DB-backed Warp, Forge, and Piebald providers (#949)

parse-diff v1 (#662) rejected Warp, Forge, and Piebald because their sync phases had woven-in change detectors and no `DiscoverFunc`. The provider facade (#876–#885, #924) made that reason obsolete — all three now have a unified `Discover()` via `dbBackedProviderFactory` — but both parse-diff gates still keyed on `FileBased`, which is false for these shared-SQLite stores.

This relaxes the two gates (`parseDiffAgentDiscoverable`, `parseDiffAgentSupported`) to admit provider-authoritative agents with registered factories, instead of flipping `FileBased`: that flag is read at nine-plus other sites (watcher, sync engine, token accounting, remote sync, SSH resolve, settings) and genuinely means "reads a literal per-session file", so flipping it would change unrelated behavior.

Two hazards the wider gate exposed are handled in the same change:

- Virtual `<db>#<sessionID>` sources cannot be stat'd, so the raced-skew reclassification from #805 would have masked every real drift on these agents as "raced". `stripVirtualSourceSuffix` now knows their DB filenames and `parseDiffSourceReliableForRaced` re-requires `FileBased`, so DB-backed agents fail closed toward reporting a change rather than masking one.
- These providers discover one source per session (like OpenCode, unlike per-DB Kiro), so `--limit` presence-keying moved to a shared per-session base list; sessions cut by `--limit` now report "not sampled" instead of false-positive presence findings.

Quack (#930) is out of scope: it is the DuckDB remote-sync transport, not a registry agent with session sources to re-parse.

`--limit` ordering: the provider stamps each session's real mtime onto an additive, advisory `SourceRef.DiscoveryMTimeNS` while `Discover()` already has the store's session metas in hand, and the parse-diff sampler prefers it over the failed-stat fallback — so limited runs sample these virtual sources newest-first like file-based agents. The field is ordering-only metadata; skip-cache and data-version freshness still resolve through `Fingerprint`, and the raced-guard is unchanged.

Where to look: `internal/sync/parsediff.go` (gate, raced predicate, per-session base keying) and `internal/sync/parsediff_dbbacked_test.go` for the end-to-end coverage.



Co-authored-by: Matthew Jacobs <mjacobs@users.noreply.github.com>

Author: mjacobs

cmd/agentsview/parse_diff.go

@@ -83,7 +83,7 @@ func newParseDiffCommand() *cobra.Command {
 		},
 	}
 	cmd.Flags().StringArrayVar(&cfg.Agents, "agent", nil,
-		"Restrict to these agents (repeatable; default: all file-based agents)")
+		"Restrict to these agents (repeatable; default: all re-parseable agents)")
 	cmd.Flags().IntVar(&cfg.Limit, "limit", 0,
 		"Re-parse only the N most recently modified source files (0 = all)")
 	cmd.Flags().BoolVar(&cfg.FailOnChange, "fail-on-change", false,
@@ -265,9 +265,12 @@ func parseDiffSupportedAgents() []string {
 }
 
 func parseDiffAgentSupported(def parser.AgentDef) bool {
-	if !def.FileBased {
-		return false
-	}
+	// A provider-authoritative agent with a registered factory has a
+	// Discover()/Parse() parse-diff can re-parse, whether it reads literal
+	// per-session files or a shared SQLite store it fans out per session
+	// (Kiro, OpenCode, Forge, Piebald, Warp). FileBased is not consulted:
+	// import-only agents are already excluded because they are not
+	// provider-authoritative.
 	switch parser.ProviderMigrationModes()[def.Type] {
 	case parser.ProviderMigrationProviderAuthoritative:
 		_, ok := parser.ProviderFactoryByType(def.Type)

cmd/agentsview/parse_diff_test.go

@@ -58,20 +58,27 @@ func TestParseDiff_UnknownAgentListsSupported(t *testing.T) {
 		assert.Contains(t, err.Error(), want,
 			"error should list supported agent %q", want)
 	}
-	for _, unwanted := range []string{"forge", "piebald", "warp"} {
+	// The DB-backed provider-authoritative agents are re-parseable through
+	// their providers, so they appear in the supported list too.
+	for _, want := range []string{"forge", "piebald", "warp"} {
+		assert.Contains(t, err.Error(), want,
+			"error should list supported DB-backed agent %q", want)
+	}
+	// Import-only agents remain unsupported and must not be listed.
+	for _, unwanted := range []string{"claude-ai", "chatgpt"} {
 		assert.NotContains(t, err.Error(), unwanted,
-			"error should not list unsupported agent %q", unwanted)
+			"error should not list import-only agent %q", unwanted)
 	}
 }
 
 func TestParseDiff_RejectsAgentsWithoutOnDiskSource(t *testing.T) {
+	// Only import-only agents have no source to re-parse. The DB-backed
+	// provider-authoritative agents (Forge/Piebald/Warp) are re-parseable
+	// through their providers and are covered as supported elsewhere.
 	tests := []struct {
 		name  string
 		agent string
 	}{
-		{"database-backed forge", "forge"},
-		{"database-backed piebald", "piebald"},
-		{"database-backed warp", "warp"},
 		{"import-only claude-ai", "claude-ai"},
 		{"import-only chatgpt", "chatgpt"},
 	}
@@ -121,6 +128,11 @@ func TestParseDiffAgentTypes(t *testing.T) {
 			in:   []string{"omp"},
 			want: []string{"omp"},
 		},
+		{
+			name: "db-backed provider-authoritative agents",
+			in:   []string{"forge", "piebald", "warp"},
+			want: []string{"forge", "piebald", "warp"},
+		},
 		{
 			name: "trims and lowercases",
 			in:   []string{" Claude "},
@@ -137,8 +149,8 @@ func TestParseDiffAgentTypes(t *testing.T) {
 			wantErr: `unknown agent "nope"`,
 		},
 		{
-			name:    "db-backed agent",
-			in:      []string{"forge"},
+			name:    "import-only agent",
+			in:      []string{"claude-ai"},
 			wantErr: "no on-disk source to re-parse",
 		},
 	}
@@ -168,12 +180,13 @@ func TestParseDiffSupportedAgentsIncludesProviderAuthoritativeAgents(t *testing.
 	supported := parseDiffSupportedAgents()
 	modes := parser.ProviderMigrationModes()
 	// Build the expected set from the registry so the contract covers every
-	// current file-based, provider-authoritative agent and stays correct as
-	// the migration manifest changes, rather than a hand-maintained subset.
+	// current provider-authoritative agent and stays correct as the migration
+	// manifest changes, rather than a hand-maintained subset. FileBased is not
+	// part of the gate: DB-backed provider-authoritative agents
+	// (Forge/Piebald/Warp) are re-parseable through their providers too.
 	checked := 0
 	for _, def := range parser.Registry {
-		if !def.FileBased ||
-			modes[def.Type] != parser.ProviderMigrationProviderAuthoritative {
+		if modes[def.Type] != parser.ProviderMigrationProviderAuthoritative {
 			continue
 		}
 		checked++
@@ -183,7 +196,23 @@ func TestParseDiffSupportedAgentsIncludesProviderAuthoritativeAgents(t *testing.
 			"parse-diff supported list must include %s", def.Type)
 	}
 	require.Positive(t, checked,
-		"expected at least one file-based provider-authoritative agent")
+		"expected at least one provider-authoritative agent")
+
+	// Explicitly pin the DB-backed provider-authoritative agents so a
+	// regression that re-adds a FileBased gate to the parse-diff support
+	// check is caught by name, not just by the registry-wide sweep above.
+	for _, agent := range []parser.AgentType{
+		parser.AgentForge, parser.AgentPiebald, parser.AgentWarp,
+	} {
+		def, ok := parser.AgentByType(agent)
+		require.True(t, ok, "agent %s", agent)
+		assert.False(t, def.FileBased,
+			"%s is expected to be DB-backed (FileBased=false)", agent)
+		assert.True(t, parseDiffAgentSupported(def),
+			"DB-backed %s must be supported by parse-diff", agent)
+		assert.Contains(t, supported, string(agent),
+			"parse-diff supported list must include DB-backed %s", agent)
+	}
 }
 
 func TestParseDiff_EmptyArchiveRunsClean(t *testing.T) {

internal/parser/db_backed_provider.go

@@ -190,11 +190,14 @@ func (s dbBackedSourceSet) Discover(ctx context.Context) ([]SourceRef, error) {
 			return nil, err
 		}
 		for _, meta := range metas {
-			addJSONLSource(
-				s.newSourceRef(root, dbPath, meta.SessionID, meta.VirtualPath),
-				&sources,
-				seen,
-			)
+			ref := s.newSourceRef(root, dbPath, meta.SessionID, meta.VirtualPath)
+			// Carry the per-session mtime captured here so parse-diff's --limit
+			// sampler can order these virtual "<db>#<sessionID>" sources by each
+			// session's real mtime rather than stat'ing a path that has no
+			// on-disk existence. Ordering metadata only: skip-cache and
+			// data-version freshness still resolve through Fingerprint.
+			ref.DiscoveryMTimeNS = meta.FileMtime
+			addJSONLSource(ref, &sources, seen)
 		}
 	}
 	sortJSONLSources(sources)
@@ -465,7 +468,7 @@ func newForgeProviderFactory(def AgentDef) ProviderFactory {
 func forgeProviderSpec() dbBackedProviderSpec {
 	return dbBackedProviderSpec{
 		agent:  AgentForge,
-		dbName: forgeDBFilename,
+		dbName: ForgeDBFilename,
 		findDB: forgeDBPath,
 		listMeta: func(dbPath string) ([]dbBackedSessionMeta, error) {
 			metas, err := ListForgeSessionMeta(dbPath)
@@ -496,7 +499,7 @@ func newPiebaldProviderFactory(def AgentDef) ProviderFactory {
 func piebaldProviderSpec() dbBackedProviderSpec {
 	return dbBackedProviderSpec{
 		agent:  AgentPiebald,
-		dbName: piebaldDBFilename,
+		dbName: PiebaldDBFilename,
 		findDB: piebaldDBPath,
 		listMeta: func(dbPath string) ([]dbBackedSessionMeta, error) {
 			metas, err := ListPiebaldSessionMeta(dbPath)
@@ -527,7 +530,7 @@ func newWarpProviderFactory(def AgentDef) ProviderFactory {
 func warpProviderSpec() dbBackedProviderSpec {
 	return dbBackedProviderSpec{
 		agent:  AgentWarp,
-		dbName: warpDBFilename,
+		dbName: WarpDBFilename,
 		findDB: warpDBPath,
 		listMeta: func(dbPath string) ([]dbBackedSessionMeta, error) {
 			metas, err := ListWarpSessionMeta(dbPath)

internal/parser/db_backed_provider_test.go

@@ -74,7 +74,7 @@ func TestForgeProviderSourceMethodsAndParse(t *testing.T) {
 	})
 	require.True(t, ok)
 
-	assertDBBackedWatchPlan(t, provider, root, forgeDBFilename)
+	assertDBBackedWatchPlan(t, provider, root, ForgeDBFilename)
 	assertDBBackedDiscoverFindFingerprint(
 		t, provider, root, dbPath, "conv-001",
 	)
@@ -109,7 +109,7 @@ func TestPiebaldProviderSourceMethodsAndParse(t *testing.T) {
 	})
 	require.True(t, ok)
 
-	assertDBBackedWatchPlan(t, provider, root, piebaldDBFilename)
+	assertDBBackedWatchPlan(t, provider, root, PiebaldDBFilename)
 	assertDBBackedDiscoverFindFingerprint(
 		t, provider, root, dbPath, "42",
 	)
@@ -152,7 +152,7 @@ func TestWarpProviderSourceMethodsAndParse(t *testing.T) {
 	})
 	require.True(t, ok)
 
-	assertDBBackedWatchPlan(t, provider, root, warpDBFilename)
+	assertDBBackedWatchPlan(t, provider, root, WarpDBFilename)
 	assertDBBackedDiscoverFindFingerprint(
 		t, provider, root, dbPath, "conv-001",
 	)
@@ -328,7 +328,7 @@ func TestDBBackedProviderRejectsInvalidStoredVirtualPaths(t *testing.T) {
 	for _, path := range []string{
 		dbPath + "#",
 		filepath.Join(root, "forge-copy.db") + "#conv-001",
-		filepath.Join(root, "nested", forgeDBFilename) + "#conv-001",
+		filepath.Join(root, "nested", ForgeDBFilename) + "#conv-001",
 	} {
 		_, ok, err := provider.FindSource(context.Background(), FindSourceRequest{
 			StoredFilePath:     path,

internal/parser/forge.go

@@ -12,7 +12,8 @@ import (
 	"github.com/tidwall/gjson"
 )
 
-const forgeDBFilename = ".forge.db"
+// ForgeDBFilename is the Forge session store filename inside its data dir.
+const ForgeDBFilename = ".forge.db"
 
 // ForgeSessionMeta is lightweight metadata for a session,
 // used to detect changes without parsing messages.
@@ -27,7 +28,7 @@ func forgeDBPath(dir string) string {
 	if dir == "" {
 		return ""
 	}
-	path := filepath.Join(dir, forgeDBFilename)
+	path := filepath.Join(dir, ForgeDBFilename)
 	info, err := os.Stat(path)
 	if err != nil || info.IsDir() {
 		return ""

internal/parser/piebald.go

@@ -11,7 +11,8 @@ import (
 	"time"
 )
 
-const piebaldDBFilename = "app.db"
+// PiebaldDBFilename is the Piebald session store filename inside its data dir.
+const PiebaldDBFilename = "app.db"
 
 // PiebaldSessionMeta is lightweight metadata for a Piebald chat.
 type PiebaldSessionMeta struct {
@@ -25,7 +26,7 @@ func piebaldDBPath(dir string) string {
 	if dir == "" {
 		return ""
 	}
-	path := filepath.Join(dir, piebaldDBFilename)
+	path := filepath.Join(dir, PiebaldDBFilename)
 	info, err := os.Stat(path)
 	if err != nil || info.IsDir() {
 		return ""

internal/parser/provider.go

@@ -176,6 +176,16 @@ type SourceRef struct {
 	FingerprintKey string
 	// ProjectHint is advisory metadata for UI grouping and may be empty.
 	ProjectHint string
+	// DiscoveryMTimeNS is an optional per-source modification time in Unix
+	// nanoseconds captured at discovery. Providers whose sources are virtual --
+	// a shared store fanned out to one source per session, where DisplayPath is
+	// "<db>#<sessionID>" and os.Stat cannot resolve a real mtime -- set it so
+	// ordering consumers (parse-diff's --limit sampler) can rank sources by each
+	// session's real mtime instead of a failed stat that collapses to 0. Zero
+	// means unset. It is advisory ordering metadata only: it is never persisted
+	// and must not be used for skip-cache or data-version freshness, which go
+	// through Fingerprint.
+	DiscoveryMTimeNS int64
 	// Opaque is in-memory-only source state: never persisted and never required
 	// for lookup from persisted rows, so any source that must survive a restart
 	// has to be recoverable from Key, DisplayPath, FingerprintKey,

internal/parser/warp.go

@@ -10,7 +10,8 @@ import (
 	"time"
 )
 
-const warpDBFilename = "warp.sqlite"
+// WarpDBFilename is the Warp session store filename inside its data dir.
+const WarpDBFilename = "warp.sqlite"
 
 // WarpSessionMeta is lightweight metadata for a session,
 // used to detect changes without parsing messages.
@@ -486,7 +487,7 @@ func parseWarpTimestamp(s string) time.Time {
 // warpDBPath returns the path to warp.sqlite inside the
 // given directory, or "" if it doesn't exist.
 func warpDBPath(dir string) string {
-	candidate := filepath.Join(dir, warpDBFilename)
+	candidate := filepath.Join(dir, WarpDBFilename)
 	if _, err := os.Stat(candidate); err == nil {
 		return candidate
 	}

internal/sync/engine_integration_test.go

@@ -34,6 +34,7 @@ type testEnv struct {
 	mimocodeDir       string
 	forgeDir          string
 	piebaldDir        string
+	warpDir           string
 	iflowDir          string
 	ampDir            string
 	piDir             string
@@ -115,6 +116,7 @@ func setupTestEnv(t *testing.T, opts ...TestEnvOption) *testEnv {
 		mimocodeDir:       t.TempDir(),
 		forgeDir:          t.TempDir(),
 		piebaldDir:        t.TempDir(),
+		warpDir:           t.TempDir(),
 		iflowDir:          t.TempDir(),
 		ampDir:            t.TempDir(),
 		piDir:             t.TempDir(),
@@ -183,6 +185,7 @@ func setupTestEnv(t *testing.T, opts ...TestEnvOption) *testEnv {
 			parser.AgentMiMoCode:       {env.mimocodeDir},
 			parser.AgentForge:          {env.forgeDir},
 			parser.AgentPiebald:        {env.piebaldDir},
+			parser.AgentWarp:           {env.warpDir},
 			parser.AgentIflow:          {env.iflowDir},
 			parser.AgentAmp:            {env.ampDir},
 			parser.AgentPi:             {env.piDir},
@@ -262,6 +265,10 @@ func assignFocusedAgentDir(
 		env.mimocodeDir = dir
 	case parser.AgentPiebald:
 		env.piebaldDir = dir
+	case parser.AgentForge:
+		env.forgeDir = dir
+	case parser.AgentWarp:
+		env.warpDir = dir
 	case parser.AgentPi:
 		env.piDir = dir
 	case parser.AgentOMP: