feat(sync): add machine-labeled session sources (#1170)

Add filesystem-only `[[session_sources]]` entries with `agent`, `dir`,
and
optional `machine`. Structured sources are additive to existing
per-agent
directory arrays, defaults, and environment variables; when roots
overlap, the
structured entry supplies the machine label. Configured paths keep the
spelling
the user wrote them in, and a separate cleaned comparison key collapses
equivalent roots, so Windows-style entries survive a config round-trip.

A session's machine is resolved from the configured root that produced
it and
is assigned once, when the session is first ingested. After that the
label is
immutable: ordinary periodic, watcher-driven, incremental,
provider-backed, and
single-session syncs all retain the stored value rather than adopting a
newly
configured one. `agentsview sync --full` preserves stored labels while
rebuilding the archive; it is not a relabel operation. Changing a
configured
label therefore affects only sessions discovered afterward, which makes
editing
configuration safe rather than destructive. Filesystem labels do not
namespace
native session IDs.

Because relabeling is no longer part of sync, this removes the
machine-only
update for trashed sessions, the all-machines baseline scan, and the
ownership
baseline index keyed without machine. Watch reconciliation still uses
the
baseline for the machine that originally admitted a session, so
per-event work
stays bounded by the changed batch.

An earlier revision of this branch chased reattribution through each new
writer,
trash path, snapshot path, and reconciliation edge. That approach kept
widening
the persistent-archive surface and reintroducing consistency bugs, so it
was
replaced with the ingestion-time contract above. A one-shot relabel
command is
deliberately deferred: it needs its own invariants and recovery tests,
and it is
not required to ship labeled ingestion.

The filesystem sync guide documents Git, rsync/file copy, and
NFS/shared-mount
topologies, including atomic publication, archive ownership, freshness,
native-ID deduplication, label-change behavior, and when PostgreSQL is a
better
fit.

`session_sources` intentionally rejects `s3://` roots. Existing Claude
and Codex
S3 configuration and behavior remain unchanged through their existing
per-agent
settings.

Reviewers should start at `internal/sync/engine.go`, where machine
resolution
and the preserve-on-upsert rule live, then `internal/config/config.go`
for
parsing and path handling. `docs/superpowers/specs/` carries the design
rationale.

This branch contains no DuckDB changes. Mirror source-machine
attribution
already landed in #1302, and this PR neither duplicates nor modifies it.

---------

Co-authored-by: Matthew Jacobs <mjacobs@apache.org>

Author: xkrogen

README.md

@@ -480,6 +480,29 @@ March 2026), which shares that same database. *Kilo (legacy)* is the legacy
 RooCode-derived VS Code extension that wrote per-task JSON under
 `kilocode.kilo-code/tasks/`.
 
+## Filesystem Session Sync
+
+One primary AgentsView instance can ingest native agent session directories
+copied or mounted from other machines without PostgreSQL:
+
+```toml
+[[session_sources]]
+agent = "copilot"
+dir = "/srv/session-archive/buildbox/copilot"
+machine = "buildbox"
+```
+
+Structured sources are additive to existing `copilot_dirs`,
+`claude_project_dirs`, and other per-agent settings. They label sessions by
+source machine without namespacing native session IDs. Transport source session
+files only -- never copy `sessions.db` or its WAL files. Machine labels are
+captured at first ingestion; ordinary sync and `agentsview sync --full` preserve
+the stored label. Changing attribution for existing sessions is not currently
+supported.
+
+See the [Filesystem Session Sync guide](https://agentsview.io/filesystem-sync/)
+for Git, rsync, shared-mount, freshness, and operational guidance.
+
 ## PostgreSQL Sync
 
 Push session data to a shared PostgreSQL instance for team dashboards:
@@ -633,6 +656,7 @@ Full docs at **[agentsview.io](https://agentsview.io)**:
 [Usage Guide](https://agentsview.io/usage/) --
 [CLI Reference](https://agentsview.io/commands/) --
 [Configuration](https://agentsview.io/configuration/) --
+[Filesystem Sync](https://agentsview.io/filesystem-sync/) --
 [Architecture](https://agentsview.io/architecture/)
 
 ______________________________________________________________________

cmd/agentsview/archive_query_backend.go

@@ -250,6 +250,7 @@ func (b localArchiveQueryBackend) SessionUsage(
 	if known && !b.skipFreshData {
 		engine := sync.NewEngine(b.database, sync.EngineConfig{
 			AgentDirs:               b.cfg.AgentDirs,
+			SourceMachines:          b.cfg.SourceMachines,
 			IncludeCwdPrefixes:      b.cfg.SyncIncludeCwdPrefixes,
 			Machine:                 b.cfg.LocalMachineName,
 			BlockedResultCategories: b.cfg.ResultContentBlockedCategories,

cmd/agentsview/archive_write_backend.go

@@ -936,6 +936,7 @@ func (b *localArchiveWriteBackend) DuckDBPushWatch(
 
 	engine := syncpkg.NewEngine(b.database, syncpkg.EngineConfig{
 		AgentDirs:               b.appCfg.AgentDirs,
+		SourceMachines:          b.appCfg.SourceMachines,
 		IncludeCwdPrefixes:      b.appCfg.SyncIncludeCwdPrefixes,
 		Machine:                 b.appCfg.LocalMachineName,
 		BlockedResultCategories: b.appCfg.ResultContentBlockedCategories,
@@ -1053,6 +1054,7 @@ func (b *localArchiveWriteBackend) PGPushWatch(
 
 	engine := syncpkg.NewEngine(b.database, syncpkg.EngineConfig{
 		AgentDirs:               b.appCfg.AgentDirs,
+		SourceMachines:          b.appCfg.SourceMachines,
 		IncludeCwdPrefixes:      b.appCfg.SyncIncludeCwdPrefixes,
 		Machine:                 b.appCfg.LocalMachineName,
 		BlockedResultCategories: b.appCfg.ResultContentBlockedCategories,

cmd/agentsview/main.go

@@ -296,6 +296,7 @@ func runServe(cfg config.Config, opts serveOptions) {
 		var onStartupReconciled func(sync.SyncStats, error)
 		engine = sync.NewEngine(database, sync.EngineConfig{
 			AgentDirs:               cfg.AgentDirs,
+			SourceMachines:          cfg.SourceMachines,
 			IncludeCwdPrefixes:      cfg.SyncIncludeCwdPrefixes,
 			Machine:                 cfg.LocalMachineName,
 			BlockedResultCategories: cfg.ResultContentBlockedCategories,

cmd/agentsview/parse_diff.go

@@ -127,6 +127,7 @@ func doParseDiff(cfg ParseDiffConfig) (failed bool) {
 
 	engine := sync.NewDiffEngine(database, sync.EngineConfig{
 		AgentDirs:               appCfg.AgentDirs,
+		SourceMachines:          appCfg.SourceMachines,
 		IncludeCwdPrefixes:      appCfg.SyncIncludeCwdPrefixes,
 		Machine:                 appCfg.LocalMachineName,
 		BlockedResultCategories: appCfg.ResultContentBlockedCategories,

cmd/agentsview/session_sync.go

@@ -74,6 +74,7 @@ func syncService(
 	}
 	engine := sync.NewEngine(d, sync.EngineConfig{
 		AgentDirs:          cfg.AgentDirs,
+		SourceMachines:     cfg.SourceMachines,
 		IncludeCwdPrefixes: cfg.SyncIncludeCwdPrefixes,
 		Machine:            cfg.LocalMachineName,
 	})

cmd/agentsview/sync.go

@@ -933,6 +933,7 @@ func coordinateLocalSync(
 
 	engine := sync.NewEngine(database, sync.EngineConfig{
 		AgentDirs:               appCfg.AgentDirs,
+		SourceMachines:          appCfg.SourceMachines,
 		IncludeCwdPrefixes:      appCfg.SyncIncludeCwdPrefixes,
 		Machine:                 appCfg.LocalMachineName,
 		BlockedResultCategories: appCfg.ResultContentBlockedCategories,

cmd/agentsview/sync_worker.go

@@ -360,6 +360,7 @@ func openWorkerWriteDB(cfg config.Config) (*db.DB, *writeOwnerLock, error) {
 func workerEngineConfig(cfg config.Config) sync.EngineConfig {
 	return sync.EngineConfig{
 		AgentDirs:               cfg.AgentDirs,
+		SourceMachines:          cfg.SourceMachines,
 		IncludeCwdPrefixes:      cfg.SyncIncludeCwdPrefixes,
 		Machine:                 cfg.LocalMachineName,
 		BlockedResultCategories: cfg.ResultContentBlockedCategories,

cmd/agentsview/sync_worker_test.go

@@ -99,6 +99,28 @@ func TestSyncWorkerStartupModeSyncsAndEmitsTerminalResult(t *testing.T) {
 		"public SyncStats fields must survive the NDJSON protocol")
 }
 
+func TestSyncWorkerStartupUsesConfiguredSourceMachine(t *testing.T) {
+	cfg := testConfigWithClaudeFixture(t)
+	claudeRoot := cfg.AgentDirs[parser.AgentClaude][0]
+	cfg.SourceMachines = map[parser.AgentType]map[string]string{
+		parser.AgentClaude: {claudeRoot: "archivebox"},
+	}
+
+	var out bytes.Buffer
+	require.NoError(t, runSyncWorker(cfg, "startup", &out))
+	assert.Equal(t, "ok", decodeSingleResult(t, &out).Status)
+
+	database, err := db.OpenReadOnly(cfg.DBPath)
+	require.NoError(t, err)
+	defer database.Close()
+	page, err := database.ListSessions(context.Background(), db.SessionFilter{})
+	require.NoError(t, err)
+	require.Len(t, page.Sessions, 3)
+	for _, sess := range page.Sessions {
+		assert.Equal(t, "archivebox", sess.Machine)
+	}
+}
+
 func TestSyncWorkerReportsAbortAsFailure(t *testing.T) {
 	cfg := testConfigWithClaudeFixture(t)
 	ctx, cancel := context.WithCancel(context.Background())

cmd/agentsview/usage.go

@@ -312,6 +312,7 @@ func ensureFreshData(
 	if database.NeedsResync() {
 		engine := sync.NewEngine(database, sync.EngineConfig{
 			AgentDirs:          appCfg.AgentDirs,
+			SourceMachines:     appCfg.SourceMachines,
 			IncludeCwdPrefixes: appCfg.SyncIncludeCwdPrefixes,
 			Machine:            appCfg.LocalMachineName,
 		})
@@ -336,6 +337,7 @@ func ensureFreshData(
 
 	engine := sync.NewEngine(database, sync.EngineConfig{
 		AgentDirs:          appCfg.AgentDirs,
+		SourceMachines:     appCfg.SourceMachines,
 		IncludeCwdPrefixes: appCfg.SyncIncludeCwdPrefixes,
 		Machine:            appCfg.LocalMachineName,
 	})