fix(artifact): bound folder transport replay

Folder exchanges must not rescan and rehash every immutable object while holding the daemon sync lock, because archive history grows independently of current work.

Bind durable continuation state to a unique target namespace, consume an immutable publication journal within object and byte budgets, and resume authoritative closure publication by checkpoint generation. Unchanged heads now avoid closure traversal, while interrupted journal and quarantine transitions remain replayable and fail closed.

Author: wesm

docs/artifact-sync.md

@@ -1,7 +1,6 @@
----
-title: Artifact Folder Sync
-description: Exchange normalized sessions between AgentsView archives through a trusted folder
----
+______________________________________________________________________
+
+## title: Artifact Folder Sync description: Exchange normalized sessions between AgentsView archives through a trusted folder
 
 Artifact folder sync exchanges normalized AgentsView sessions between machines
 through a folder that both machines can access. The folder can be a mounted NAS,
@@ -17,16 +16,19 @@ folder, or change ordinary provider sync behavior.
 
 !!! warning
 
-    The target contains normalized session messages and related metadata. It can
-    contain sensitive prompts, responses, tool activity, and usage data. Use only a
-    folder whose storage and access controls you trust.
+```
+The target contains normalized session messages and related metadata. It can
+contain sensitive prompts, responses, tool activity, and usage data. Use only a
+folder whose storage and access controls you trust.
+```
 
 ## First use
 
 The target must either not exist or be an empty directory. On first use,
 AgentsView creates it and adds an `.agentsview-artifacts.json` namespace marker.
-Later runs refuse an unmarked nonempty directory rather than adopting unrelated
-files.
+The marker includes a randomly generated namespace identity used to bind local
+continuation state to this exact target. Later runs refuse an unmarked nonempty
+directory rather than adopting unrelated files.
 
 Run the command once on each participating machine:
 
@@ -40,13 +42,16 @@ agentsview sync --target /mnt/team-agentsview
 
 The path can differ between machines. Each archive pulls verified immutable
 objects already in the folder, publishes its own objects, and imports supported
-peer checkpoints into its local SQLite archive. Repeating the command is safe:
-already accepted content is verified and skipped, while changed sessions publish
-a new revision.
+peer checkpoints into its local SQLite archive. Publication also appends an
+immutable change-journal entry. Each machine retains a target-bound journal
+cursor, so repeating the command processes new entries instead of rescanning and
+rehashing the folder's complete history. Changed sessions publish a new
+revision.
 
-The command performs a bounded amount of work so concurrent provider writes
-cannot keep it running forever. If the summary says that artifact work remains,
-run the same command again:
+The command enforces object-count and decoded-byte budgets for both inbound and
+outbound transport work. Continuation cursors are durable, so later runs resume
+after the last accepted object rather than restarting at the first object. If
+the summary says that artifact work remains, run the same command again:
 
 ```text
 Artifact work remains; run the sync command again.
@@ -96,6 +101,9 @@ restored from backup, keep only one active writer for that restored origin.
   machine retains imported sessions in its own SQLite archive.
 - Objects are content-addressed and immutable. Conflicting content under an
   existing identity fails closed.
+- Journal entries are immutable and sequence numbered. AgentsView advances a
+  local cursor only after the referenced object has been read, verified, and
+  accepted, making interruption and retry safe.
 - Invalid complete objects are quarantined so one corrupt peer artifact does not
   permanently block unrelated origins.
 - Folder operations are serialized between cooperating AgentsView processes. Do

internal/artifact/sync.go

@@ -95,7 +95,10 @@ func SyncWithRepository(
 	forbidden = append(forbidden, repository.rootPath)
 	transport, err := OpenFolderTransport(
 		opts.Target,
-		FolderTransportOptions{ForbiddenRoots: forbidden},
+		FolderTransportOptions{
+			ForbiddenRoots: forbidden,
+			StateStore:     databaseFolderTransportState{database: database},
+		},
 	)
 	if err != nil {
 		return SyncResult{}, err
@@ -154,10 +157,29 @@ func SyncWithRepository(
 	if err != nil {
 		return result, err
 	}
-	result.More = exportMore || importMore
+	result.More = exportMore || exchanged.More || importMore
 	return result, nil
 }
 
+type databaseFolderTransportState struct {
+	database *db.DB
+}
+
+func (s databaseFolderTransportState) LoadFolderTransportState(
+	_ context.Context,
+	namespaceID string,
+) (string, error) {
+	return s.database.GetSyncState("artifact_transport_" + namespaceID)
+}
+
+func (s databaseFolderTransportState) SaveFolderTransportState(
+	_ context.Context,
+	namespaceID string,
+	value string,
+) error {
+	return s.database.SetSyncState("artifact_transport_"+namespaceID, value)
+}
+
 func validateArtifactSyncOptions(opts SyncOptions) error {
 	if strings.TrimSpace(opts.Target) == "" {
 		return fmt.Errorf(

internal/artifact/sync_test.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"os"
 	"path/filepath"
 	"testing"
 	"time"
@@ -69,6 +70,7 @@ func TestArtifactSyncTwoNodeFolderRoundTripAndReplay(t *testing.T) {
 	require.NoError(t, err)
 	require.Len(t, messages, 2)
 	assert.Equal(t, "world", messages[1].Content)
+	journalSequenceBeforeReplay := readTestFolderJournalSequence(t, target)
 
 	replay, err := SyncWithRepository(
 		t.Context(),
@@ -80,6 +82,12 @@ func TestArtifactSyncTwoNodeFolderRoundTripAndReplay(t *testing.T) {
 	assert.Zero(t, replay.ImportedSessions)
 	assert.Zero(t, replay.ImportedMessages)
 	assert.False(t, replay.More)
+	assert.Equal(
+		t,
+		journalSequenceBeforeReplay,
+		readTestFolderJournalSequence(t, target),
+		"an unchanged authoritative head must not replay its closure",
+	)
 
 	require.NoError(t, databaseA.ReplaceSessionMessages("one", []db.Message{
 		{
@@ -119,6 +127,16 @@ func TestArtifactSyncTwoNodeFolderRoundTripAndReplay(t *testing.T) {
 	assert.Equal(t, "updated response", updatedMessages[1].Content)
 }
 
+func readTestFolderJournalSequence(t *testing.T, target string) int64 {
+	t.Helper()
+	root, err := os.OpenRoot(filepath.Join(target, folderJournalDirectory))
+	require.NoError(t, err)
+	head, err := readFolderJournalHead(root)
+	require.NoError(t, err)
+	require.NoError(t, root.Close())
+	return head.Sequence
+}
+
 func TestArtifactSyncDoesNotIngestOrRepublishSpoofedLocalOrigin(
 	t *testing.T,
 ) {

internal/artifact/transport.go

@@ -22,12 +22,23 @@ type Transport interface {
 type ExchangeResult struct {
 	Received  int
 	Published int
+	More      bool
 }
 
 // FolderTransportOptions defines roots that must remain disjoint from the
 // external artifact target.
 type FolderTransportOptions struct {
 	ForbiddenRoots []string
+	MaxObjects     int
+	MaxBytes       int64
+	StateStore     FolderTransportStateStore
+}
+
+// FolderTransportStateStore persists target-bound continuation state between
+// bounded exchanges. Implementations must treat namespaceID as an opaque key.
+type FolderTransportStateStore interface {
+	LoadFolderTransportState(context.Context, string) (string, error)
+	SaveFolderTransportState(context.Context, string, string) error
 }
 
 type transportChangeRecorder interface {