From 33ca0caeabacc6c632fb4ec00fda3abe88c2e3e8 Mon Sep 17 00:00:00 2001
From: "Snow Lee (Sungwon)" <snow@runbear.io>
Date: Wed, 12 Aug 2026 16:10:10 -0700
Subject: [PATCH] fix(sync): connecting a folder adopts the project's files
 instead of forking them (#159)

A device's first cycle on a volume was treated as a concurrent edit for every
path the project already held. Whichever side's clock happened to sort higher
won -- so a joiner's seeded .bdriveignore or agent-written AGENTS.md could
replace the team's -- and the loser landed beside it as a
.bdrive-conflict-<device>-<time> file.

A first cycle is a join, not an edit. Cycle step 1b holds the scan's ops back
over the pull and demotes any whose path the project already holds to lamport
0, which sorts under every op a project can carry (scan's clock starts at 1).
The project's version then wins deterministically on every device, and
conflictCopies skips those ops the way it already skips re-asserted ones. The
local content is still journaled and pushed, so it stays in History and
`bdrive restore --list <path>` can bring it back. Reported as `adopted: N`.

Concurrent edits after the join are untouched.


Claude-Session: https://claude.ai/code/session_01GLCyEWP2XZhYjBssvdCDQm

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   5 +
 architecture/cli-sync.md                      |   5 +-
 cmd/bdrive/helpers.go                         |   3 +
 internal/syncer/flows_test.go                 |  92 ++++++++++--
 internal/syncer/sec_peer_test.go              |  20 ++-
 internal/syncer/syncer.go                     | 100 +++++++++++--
 internal/webapp/cli_e2e_test.go               | 135 +++++++++++++++++-
 .../src/content/docs/concepts/how-it-works.md |   9 ++
 8 files changed, 339 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index d3b75b8..824d89e 100644
--- a/README.md
+++ b/README.md
@@ -109,6 +109,11 @@ actually read (and which hot ones nobody maintains).
 - **Conflict-safe** — concurrent edits resolve deterministically
   (last-writer-wins), and the losing version is preserved as a
   `name.bdrive-conflict-<device>-<time>` file. Nothing is silently dropped.
+  Connecting a folder is not a concurrent edit: on the first sync, files the
+  project already has (its `.bdriveignore`, `AGENTS.md`, anything a checkout
+  brought along) keep the project's version — no conflict copies. Your copy is
+  journaled as a superseded version, so `bdrive restore --list <path>` still
+  has it.
 - **Your agent's skills sync too** — `.claude/skills`, `.claude/commands`,
   `.claude/agents`, `AGENTS.md` and `CLAUDE.md` are ordinary files in the
   project, so a skill one person writes is on every teammate's disk before
diff --git a/architecture/cli-sync.md b/architecture/cli-sync.md
index 39880fe..f19496c 100644
--- a/architecture/cli-sync.md
+++ b/architecture/cli-sync.md
@@ -27,18 +27,19 @@ classDiagram
     }
     note for Session "syncer also exposes LogEntries (causal order, what bdrive restore walks) plus DisplayTime / SortForDisplay — the newest-first-by-clock order bdrive log prints"
     note for Session "Restore writes a historical blob back into the working folder as an ordinary edit (fetching it from the hub when this device never held it) — the next Cycle journals it like any other change; it takes no lock and appends to no journal itself"
-    note for Session "internal/syncer — scan → commit local ops → pull peer journals → re-assert withdrawn ops → preserve conflicts → refresh rules → prune → materialize → push blobs then own journal"
+    note for Session "internal/syncer — scan → commit local ops → pull peer journals → adopt on join → re-assert withdrawn ops → preserve conflicts → refresh rules → prune → materialize → push blobs then own journal"
     note for Session "pull returns TWO lists: newly seen ops, and `gone` — ops a peer deleted from a journal this device had already applied. A peer cannot un-say what we already hold: stillHold re-signs each still-held put into OUR journal (reassertNote). Pull resumes at a byte offset by prefix-matching the local journal copy, so a peer's growing journal is read once"
     note for Session "Bounds and hardening applied throughout: sizeBound/pullBound cap a fetch against the op's declared size, maxPeerJournals caps how many peers one cycle reads, absorbLamport/tickLamport refuse an absurd peer clock and saturate instead of wrapping, safeMode masks a materialized file to 0777 &^ 0022 (no setuid/setgid, no group/other write), and safeDevice + os.SameFile keep a peer's device id from naming this device's own journal file"
     note for Session "Prune (bdrive forget / sync --prune, never the daemon) journals a delete for every replayed path the SHARED ignore rules exclude — the include scope is per-device and must never prune it"
 
     class Result {
         +LocalOps +PulledOps
-        +Conflicts +Pruned +Materialized
+        +Conflicts +Adopted +Pruned +Materialized
         +Pushed +Offline +OfflineErr
         +ReadOnly +NoAccess +AccessErr
         +Reason() string
     }
+    note for Result "Adopted counts the paths a JOINING device gave to the project (Cycle step 1b). A first cycle is a join, not an edit: a local file at a path the project already holds is demoted to lamport 0 (adoptNote), so the project's version wins on every device and no conflict copy is made — the local content stays journaled and pushed, which is what bdrive restore reads"
     note for Result "Offline / ReadOnly / NoAccess are three different answers: unreachable (retry all), push refused (pull-only), pull refused (pause, touch nothing)"
     note for Result "Reason() is accessReason(AccessErr): the hub's own sentence for a refusal, minus the wrapper chain, dropped unless it passes journal.SafeText. 'read-only' summarizes the STATUS CODE — the sentence is the only thing that tells a device-registration 403 from a project the user really is a reader on"
 
diff --git a/cmd/bdrive/helpers.go b/cmd/bdrive/helpers.go
index 01caa81..7309781 100644
--- a/cmd/bdrive/helpers.go
+++ b/cmd/bdrive/helpers.go
@@ -195,6 +195,9 @@ func printCycle(res *syncer.Result) {
 	if res.Conflicts > 0 {
 		fmt.Printf("  conflicts:      %d (preserved as *.bdrive-conflict-* files)\n", res.Conflicts)
 	}
+	if res.Adopted > 0 {
+		fmt.Printf("  adopted:        %d file(s) replaced by the project's version (yours: `bdrive restore --list <path>`)\n", res.Adopted)
+	}
 	if res.Pruned > 0 {
 		fmt.Printf("  pruned:         %d path(s) removed from the hub (kept on disk)\n", res.Pruned)
 	}
diff --git a/internal/syncer/flows_test.go b/internal/syncer/flows_test.go
index 6e0a1e1..06fcfd9 100644
--- a/internal/syncer/flows_test.go
+++ b/internal/syncer/flows_test.go
@@ -116,8 +116,11 @@ func TestConnectWithIdenticalLocalContent(t *testing.T) {
 	}
 }
 
-// Same story with a stale divergent copy: nothing is silently lost — the
-// devices converge on one version and the other survives as a conflict copy.
+// Same story with a stale divergent copy. Joining is an adoption, not a merge:
+// the project's version wins on every device — even though the joiner's copy is
+// the later write — and no conflict copy is made. The joiner's content is not
+// lost, it is journaled (and pushed) as a superseded version, which is what
+// `bdrive restore` reads.
 func TestConnectWithDivergentLocalContent(t *testing.T) {
 	be := sharedRemote(t)
 	a := newDevice(t, "deva", be)
@@ -127,23 +130,86 @@ func TestConnectWithDivergentLocalContent(t *testing.T) {
 	b := newDevice(t, "devb", be)
 	time.Sleep(10 * time.Millisecond)
 	write(t, b.Folder, "docs/guide.md", "stale local version")
-	cycle(t, b)
+	if res := cycle(t, b); res.Adopted != 1 {
+		t.Fatalf("Adopted = %d, want 1", res.Adopted)
+	}
 	cycle(t, a)
 	cycle(t, b)
 
-	av, bv := read(t, a.Folder, "docs/guide.md"), read(t, b.Folder, "docs/guide.md")
-	if av != bv {
-		t.Fatalf("devices diverged: %q vs %q", av, bv)
-	}
-	survived := map[string]bool{av: true}
 	for _, s := range []*Session{a, b} {
-		for _, p := range conflictFiles(t, s.Folder) {
-			rel, _ := filepath.Rel(s.Folder, p)
-			survived[read(t, s.Folder, rel)] = true
+		if got := read(t, s.Folder, "docs/guide.md"); got != "hub version" {
+			t.Fatalf("%s guide.md = %q, want the project's version", s.Device.ID, got)
+		}
+		if c := conflictFiles(t, s.Folder); len(c) != 0 {
+			t.Fatalf("%s: joining made conflict copies: %v", s.Device.ID, c)
 		}
 	}
-	if !survived["hub version"] || !survived["stale local version"] {
-		t.Fatalf("a version was silently lost; surviving: %v", survived)
+	// The superseded content is still in history, on both devices.
+	for _, s := range []*Session{a, b} {
+		ops, err := s.Store.AllOps()
+		if err != nil {
+			t.Fatal(err)
+		}
+		var found bool
+		for _, op := range ops {
+			if op.Path == "docs/guide.md" && s.Store.HasBlob(op.Blob) {
+				if body, err := os.ReadFile(s.Store.BlobPath(op.Blob)); err == nil && string(body) == "stale local version" {
+					found = true
+				}
+			}
+		}
+		if !found {
+			t.Fatalf("%s: the joiner's version is not recoverable from history", s.Device.ID)
+		}
+	}
+}
+
+// The reported connect experience: a folder that already holds a .bdriveignore
+// (`bdrive init` seeds one) and an agent-written AGENTS.md joins a project that
+// has its own versions of both. Neither may fork into a
+// `.bdriveignore.bdrive-conflict-<device>-<time>` file, and neither may have the
+// joiner's copy overwrite the team's. A real concurrent edit AFTER the join
+// still conflict-copies — that is a different situation and keeps its old
+// behavior.
+func TestConnectDoesNotForkIgnoreAndAgentsFiles(t *testing.T) {
+	be := sharedRemote(t)
+	a := newDevice(t, "deva", be)
+	write(t, a.Folder, ".bdriveignore", "node_modules/\n*.log\n")
+	write(t, a.Folder, "AGENTS.md", "team instructions\n")
+	cycle(t, a)
+
+	b := newDevice(t, "devb", be)
+	time.Sleep(10 * time.Millisecond)
+	write(t, b.Folder, ".bdriveignore", "# BearDrive starter\n.DS_Store\n")
+	write(t, b.Folder, "AGENTS.md", "notes my agent wrote here\n")
+	res := cycle(t, b)
+	if res.Adopted != 2 {
+		t.Fatalf("Adopted = %d, want 2 (.bdriveignore and AGENTS.md)", res.Adopted)
+	}
+	if res.Conflicts != 0 {
+		t.Fatalf("connecting made %d conflict copies, want 0", res.Conflicts)
+	}
+	cycle(t, a)
+	cycle(t, b)
+
+	for _, s := range []*Session{a, b} {
+		if c := conflictFiles(t, s.Folder); len(c) != 0 {
+			t.Fatalf("%s: connecting littered the folder: %v", s.Device.ID, c)
+		}
+		if got := read(t, s.Folder, "AGENTS.md"); got != "team instructions\n" {
+			t.Fatalf("%s AGENTS.md = %q, want the team's version", s.Device.ID, got)
+		}
+		if got := read(t, s.Folder, ".bdriveignore"); got != "node_modules/\n*.log\n" {
+			t.Fatalf("%s .bdriveignore = %q, want the team's version", s.Device.ID, got)
+		}
+	}
+
+	// Now a genuine concurrent edit between two devices that share the project.
+	write(t, a.Folder, "AGENTS.md", "a's edit\n")
+	write(t, b.Folder, "AGENTS.md", "b's edit\n")
+	cycle(t, a)
+	if res := cycle(t, b); res.Conflicts != 1 {
+		t.Fatalf("a real concurrent edit made %d conflict copies, want 1", res.Conflicts)
 	}
 }
 
diff --git a/internal/syncer/sec_peer_test.go b/internal/syncer/sec_peer_test.go
index fbcb561..cf053e5 100644
--- a/internal/syncer/sec_peer_test.go
+++ b/internal/syncer/sec_peer_test.go
@@ -162,16 +162,26 @@ func TestSec_SyncPeer_HostileDeviceNameCannotBreakTheConflictCopy(t *testing.T)
 	be := sharedRemote(t)
 	victim := newDevice(t, "victim", be)
 
+	// The victim syncs the project once first. A collision on a device's very
+	// first cycle is a JOIN, which Cycle step 1b resolves in the project's
+	// favour with no copy at all; the conflict copy this test is about is the
+	// ordinary concurrent edit between two devices that already share a project.
+	const warm = "already shared"
+	warmOp := secjrnOp(1, "warm.md", secjrnBlob(t, be, warm), len(warm))
+	secjrnPush(t, be, "attacker", []journal.Op{warmOp})
+	if _, err := secpeerCycle(t, victim); err != nil {
+		t.Fatal(err)
+	}
+
 	const theirs = "the peer's version"
 	blob := secjrnBlob(t, be, theirs)
-	op := secjrnOp(1, "shared.md", blob, len(theirs))
-	op.Lamport = 1
+	op := secjrnOp(2, "shared.md", blob, len(theirs))
+	op.Lamport = 2
 	op.Time = time.Now().UTC().Add(-time.Hour) // loses last-writer-wins to the victim
 	op.DeviceName = strings.Repeat("A", 300)   // lands verbatim in a filename
-	secjrnPush(t, be, "attacker", []journal.Op{op})
+	secjrnPush(t, be, "attacker", []journal.Op{warmOp, op})
 
-	// The victim edits the same file before its first sync: an ordinary
-	// concurrent edit, and exactly what makes a conflict copy.
+	// An ordinary concurrent edit, and exactly what makes a conflict copy.
 	const mine = "the victim's version"
 	write(t, victim.Folder, "shared.md", mine)
 
diff --git a/internal/syncer/syncer.go b/internal/syncer/syncer.go
index 78b82d9..e694864 100644
--- a/internal/syncer/syncer.go
+++ b/internal/syncer/syncer.go
@@ -8,6 +8,12 @@
 // state can overwrite the working folder. Concurrent edits resolve
 // deterministically last-writer-wins; the losing local version is preserved
 // as a "<name>.bdrive-conflict-<device>-<time>" file that syncs like any other.
+//
+// The exception is a device's FIRST cycle on a volume, which is a join rather
+// than an edit: a local file at a path the project already holds is adopted —
+// the project's version wins everywhere and no conflict copy is made — while
+// the local content is still journaled (below every clock the project can hold)
+// so history keeps it. See step 1b in Cycle.
 package syncer
 
 import (
@@ -107,9 +113,14 @@ func (s *Session) mountID() string {
 // cycle does nothing at all and leaves the working folder alone. Regaining
 // access self-heals on a later cycle with no manual step.
 type Result struct {
-	LocalOps     int  // local changes committed to the journal
-	PulledOps    int  // ops received from other devices
-	Conflicts    int  // conflict copies created
+	LocalOps  int // local changes committed to the journal
+	PulledOps int // ops received from other devices
+	Conflicts int // conflict copies created
+	// Adopted counts paths where this folder's own content gave way to the
+	// project's on join (step 1b). Not a conflict and not an error — the
+	// superseded content stays in history — but the user asked for none of it,
+	// so it is worth a line.
+	Adopted      int
 	Pruned       int  // paths removed from the hub by --prune (kept on disk)
 	Materialized int  // files written/removed in the working folder
 	Pushed       bool // own journal/blobs uploaded
@@ -160,7 +171,7 @@ func accessReason(err error) string {
 func (r *Result) Reason() string { return accessReason(r.AccessErr) }
 
 func (r *Result) Activity() bool {
-	return r.LocalOps > 0 || r.PulledOps > 0 || r.Conflicts > 0 || r.Pruned > 0 || r.Materialized > 0
+	return r.LocalOps > 0 || r.PulledOps > 0 || r.Conflicts > 0 || r.Adopted > 0 || r.Pruned > 0 || r.Materialized > 0
 }
 
 // The builtin exclusions (.bdrive — the mount's local identity, syncing it
@@ -229,6 +240,9 @@ func (s *Session) Cycle(ctx context.Context) (*Result, error) {
 	if err != nil {
 		return nil, err
 	}
+	// This device has never contributed to this volume: it is JOINING a project,
+	// not editing one. Step 1b is what that changes.
+	joining := st.Lamport == 0 && st.PushedOps == 0
 	filter, err := loadFilter(s.Folder, proj.Include)
 	if err != nil {
 		return nil, fmt.Errorf("load %s: %w", IgnoreFile, err)
@@ -247,8 +261,7 @@ func (s *Session) Cycle(ctx context.Context) (*Result, error) {
 		// has already synced is an upgrade, not a new joiner: seed the pair from
 		// what this mount is demonstrably syncing already (vouchedFloor) instead
 		// of taking the file's word for it.
-		if st.IgnoreAccepted == "" && st.IgnorePulled == "" && text != "" &&
-			(st.Lamport > 0 || st.PushedOps > 0) {
+		if st.IgnoreAccepted == "" && st.IgnorePulled == "" && text != "" && !joining {
 			synced := make([]string, 0, len(cache))
 			for rel := range cache {
 				synced = append(synced, rel)
@@ -265,12 +278,26 @@ func (s *Session) Cycle(ctx context.Context) (*Result, error) {
 	if err != nil {
 		return nil, fmt.Errorf("scan: %w", err)
 	}
-	if len(localOps) > 0 {
+	commitLocal := func() error {
+		if len(localOps) == 0 {
+			return nil
+		}
 		if err := s.Store.AppendOps(s.Device.ID, localOps); err != nil {
-			return nil, fmt.Errorf("append journal: %w", err)
+			return fmt.Errorf("append journal: %w", err)
 		}
 		myOps = append(myOps, localOps...)
 		res.LocalOps = len(localOps)
+		localOps = nil
+		return nil
+	}
+	if !joining {
+		// The normal path: journal local edits before the pull, so nothing
+		// remote can overwrite an edit that was never captured (see the package
+		// doc). A joining device holds its ops back for the length of the pull
+		// only — long enough to learn which paths the project already has.
+		if err := commitLocal(); err != nil {
+			return nil, err
+		}
 	}
 
 	// 2. Pull journals + blobs from other devices.
@@ -298,6 +325,12 @@ func (s *Session) Cycle(ctx context.Context) (*Result, error) {
 			// deleted, and the next cycle re-checks.
 			res.NoAccess, res.AccessErr = true, err
 			st.Access, st.AccessReason = store.AccessNone, accessReason(err)
+			// The scan already claimed these files in the state cache, which
+			// finish is about to persist — journal them or the next scan sees
+			// nothing changed and this folder's content is never captured.
+			if cerr := commitLocal(); cerr != nil {
+				return nil, cerr
+			}
 			return res, s.finish(cache, st)
 		case errors.Is(err, errBlobContent):
 			// Reported — it is the only signal a device ever gets that its hub
@@ -319,6 +352,43 @@ func (s *Session) Cycle(ctx context.Context) (*Result, error) {
 		}
 	}
 
+	// 1b. Adoption. A device joining a project it has never synced is not
+	// editing that project's files: it is bringing a folder that happens to
+	// hold some of the same paths — a git checkout of the same docs, an
+	// agent-written AGENTS.md, the .bdriveignore `bdrive init` seeds. Treating
+	// those as concurrent edits forked every one of them: whichever side's
+	// clock sorted higher won, and the other landed beside it as a
+	// `.bdrive-conflict-<device>-<time>` file. So connecting a folder littered
+	// it with copies of files nobody had edited, and half the time the joiner's
+	// stale copy is what won — replacing the team's version for everyone.
+	//
+	// The project's version wins instead, deterministically: the local op is
+	// demoted under every op the project can hold (scan's clock starts at 1, so
+	// lamport 0 loses to all of them on every device). It is still journaled and
+	// pushed, so nothing is lost — the folder's content at join time is in
+	// History and `bdrive restore` brings it back — it just never materializes.
+	if joining && len(localOps) > 0 && len(pulled) > 0 {
+		theirs := map[string]journal.Op{}
+		for _, op := range pulled {
+			if prev, ok := theirs[op.Path]; !ok || journal.Less(prev, op) {
+				theirs[op.Path] = op
+			}
+		}
+		for i, op := range localOps {
+			// Only a path the project actually HOLDS is adopted. Where its
+			// last op is a delete there is no version to adopt, so the local
+			// file is this device's own and keeps its clock.
+			if t, ok := theirs[op.Path]; ok && t.Kind == journal.KindPut {
+				localOps[i].Lamport = 0
+				localOps[i].Note = adoptNote
+				res.Adopted++
+			}
+		}
+	}
+	if err := commitLocal(); err != nil {
+		return nil, err
+	}
+
 	// 3. Preserve losing local edits as conflict copies.
 	if len(pulled) > 0 {
 		conflictOps, err := s.conflictCopies(myOps, st.PushedOps, pulled, &st)
@@ -683,6 +753,13 @@ const maxPeerJournals = 512
 // is in this device's journal, and conflictCopies depends on that distinction.
 const reassertNote = "re-asserted: the device that published it withdrew it"
 
+// adoptNote marks a local op demoted by the adoption step (1b): content this
+// folder already held at a path the project it just joined also holds. Like
+// reassertNote it is what tells conflictCopies the op is not a local edit — an
+// adopted op is a loser by construction, so preserving it as a conflict copy is
+// exactly the litter adoption exists to remove.
+const adoptNote = "kept as history: the project's version of this path was adopted on join"
+
 // errBlobContent marks "a blob's bytes are not its content address" — a
 // statement about ONE object, never about whether the hub is reachable.
 // Conflating the two let one peer integer (an understated Op.Size truncates an
@@ -997,7 +1074,12 @@ func (s *Session) conflictCopies(myOps []journal.Op, pushed int64, pulled []jour
 	}
 	unpushed := map[string]journal.Op{}
 	for _, op := range myOps[pushed:] {
-		if op.Note == reassertNote {
+		// adoptNote: the same reasoning one step removed — an adopted op was
+		// demoted precisely because the project's version wins, so it is a
+		// losing unpushed local op by construction and would conflict-copy
+		// every path a joining folder shares with the project. That is the
+		// litter step 1b exists to remove.
+		if op.Note == reassertNote || op.Note == adoptNote {
 			// A re-asserted op is not an edit this device made — it restates a
 			// peer's op that the peer withdrew, carrying that op's original
 			// (and therefore usually losing) clock. Round 9 kept it out of the
diff --git a/internal/webapp/cli_e2e_test.go b/internal/webapp/cli_e2e_test.go
index 8250caf..2343e5c 100644
--- a/internal/webapp/cli_e2e_test.go
+++ b/internal/webapp/cli_e2e_test.go
@@ -39,6 +39,14 @@ type cliEnv struct {
 }
 
 func newCLIEnv(t *testing.T) cliEnv {
+	t.Helper()
+	return newCLIEnvOn(t, nil)
+}
+
+// newCLIEnvOn is newCLIEnv against an existing hub, so a test can put two
+// DEVICES (separate BDRIVE_HOMEs, separate device identities) on one project.
+// nil starts a throwaway hub, which is the single-device default.
+func newCLIEnvOn(t *testing.T, hub *httptest.Server) cliEnv {
 	t.Helper()
 	if testing.Short() {
 		t.Skip("builds and execs the bdrive binary; skipped with -short")
@@ -49,7 +57,9 @@ func newCLIEnv(t *testing.T) cliEnv {
 		t.Fatalf("go build: %v\n%s", err, out)
 	}
 
-	hub := startTestHub(t)
+	if hub == nil {
+		hub = startTestHub(t)
+	}
 
 	// Isolate the CLI completely: fresh BDRIVE_HOME and a fresh HOME, so
 	// agent-platform detection can't see or touch the real ~/.codex etc.
@@ -282,6 +292,129 @@ func TestCLISiblingProjectMounts(t *testing.T) {
 	}
 }
 
+// Connecting a second device to an existing project, over a real hub, with the
+// files that actually collide in practice: the `.bdriveignore` init seeds and an
+// AGENTS.md an agent wrote in the folder before it was ever synced. Neither may
+// fork into a `.bdriveignore.bdrive-conflict-<device>-<time>` file, and the
+// joiner's copy may not replace the team's. The superseded content stays
+// reachable through `bdrive restore --list`.
+func TestCLIConnectAdoptsProjectVersions(t *testing.T) {
+	hub := startTestHub(t)
+	first := newCLIEnvOn(t, hub)
+
+	const teamAgents = "# Team instructions\nask before editing docs/\n"
+	owner := filepath.Join(t.TempDir(), "team")
+	if err := os.MkdirAll(owner, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(owner, "AGENTS.md"), []byte(teamAgents), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if out, err := first.run(owner, "init", "--name", "join-e2e", "--yes"); err != nil {
+		t.Fatalf("init owner: %v\n%s", err, out)
+	}
+	defer first.run(owner, "stop", owner)
+
+	// The team's ignore rules: the seeded file plus a line of their own, so the
+	// joiner's freshly seeded copy really does differ.
+	teamIgnore, err := os.ReadFile(filepath.Join(owner, ".bdriveignore"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	teamIgnore = append(teamIgnore, []byte("\n# team rules\nscratch/\n")...)
+	if err := os.WriteFile(filepath.Join(owner, ".bdriveignore"), teamIgnore, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if out, err := first.run(owner, "sync"); err != nil {
+		t.Fatalf("owner sync: %v\n%s", err, out)
+	}
+
+	// A second device, its own HOME and device identity, joining the same
+	// project from a folder that already holds its own AGENTS.md.
+	second := newCLIEnvOn(t, hub)
+	joiner := filepath.Join(t.TempDir(), "joined")
+	if err := os.MkdirAll(joiner, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	const localAgents = "notes my agent wrote in this folder\n"
+	if err := os.WriteFile(filepath.Join(joiner, "AGENTS.md"), []byte(localAgents), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	id := projectIDByName(t, first.browser, hub.URL, "join-e2e")
+	out, err := second.run(joiner, "init", "--project", id, "--yes")
+	if err != nil {
+		t.Fatalf("init joiner: %v\n%s", err, out)
+	}
+	defer second.run(joiner, "stop", joiner)
+	if !strings.Contains(out, "adopted:") {
+		t.Fatalf("init did not report adopting the project's versions:\n%s", out)
+	}
+
+	// Let both devices settle, then look at every folder involved.
+	if out, err := second.run(joiner, "sync"); err != nil {
+		t.Fatalf("joiner sync: %v\n%s", err, out)
+	}
+	if out, err := first.run(owner, "sync"); err != nil {
+		t.Fatalf("owner sync back: %v\n%s", err, out)
+	}
+	for name, folder := range map[string]string{"joiner": joiner, "owner": owner} {
+		if c := conflictCopiesUnder(t, folder); len(c) != 0 {
+			t.Errorf("%s folder has conflict copies after a plain connect: %v", name, c)
+		}
+		if got := readFile(t, filepath.Join(folder, "AGENTS.md")); got != teamAgents {
+			t.Errorf("%s AGENTS.md = %q, want the team's version", name, got)
+		}
+		if got := readFile(t, filepath.Join(folder, ".bdriveignore")); got != string(teamIgnore) {
+			t.Errorf("%s .bdriveignore = %q, want the team's version", name, got)
+		}
+	}
+
+	// Nothing was dropped: the joiner's own version is a superseded version of
+	// that path, which is exactly what `bdrive restore --list` reads.
+	versions, err := second.run(joiner, "restore", "AGENTS.md", "--list")
+	if err != nil {
+		t.Fatalf("restore --list: %v\n%s", err, versions)
+	}
+	var older string // the one version that is not the current content
+	for _, line := range strings.Split(versions, "\n") {
+		if m := restoreIDRe.FindStringSubmatch(line); m != nil && !strings.HasPrefix(strings.TrimSpace(line), "*") {
+			older = m[1]
+		}
+	}
+	if older == "" {
+		t.Fatalf("the joiner's pre-join AGENTS.md is not in history:\n%s", versions)
+	}
+	if out, err := second.run(joiner, "restore", "AGENTS.md", older); err != nil {
+		t.Fatalf("restore %s: %v\n%s", older, err, out)
+	}
+	if got := readFile(t, filepath.Join(joiner, "AGENTS.md")); got != localAgents {
+		t.Errorf("restored AGENTS.md = %q, want the joiner's pre-join content", got)
+	}
+}
+
+var restoreIDRe = regexp.MustCompile(`\b([0-9a-f]{8})\b`)
+
+func conflictCopiesUnder(t *testing.T, folder string) []string {
+	t.Helper()
+	var out []string
+	filepath.WalkDir(folder, func(p string, d os.DirEntry, err error) error {
+		if err == nil && !d.IsDir() && strings.Contains(d.Name(), ".bdrive-conflict-") {
+			out = append(out, p)
+		}
+		return nil
+	})
+	return out
+}
+
+func readFile(t *testing.T, p string) string {
+	t.Helper()
+	b, err := os.ReadFile(p)
+	if err != nil {
+		t.Fatalf("read %s: %v", p, err)
+	}
+	return string(b)
+}
+
 // One project mounted from two folders on the SAME device. The remote journal
 // key is per-device, so a second mount would restart the sequence and
 // overwrite the first mount's ops — its files would vanish from the hub. Init
diff --git a/web/docs/src/content/docs/concepts/how-it-works.md b/web/docs/src/content/docs/concepts/how-it-works.md
index bf48bc6..ddbe908 100644
--- a/web/docs/src/content/docs/concepts/how-it-works.md
+++ b/web/docs/src/content/docs/concepts/how-it-works.md
@@ -50,6 +50,15 @@ Concurrent edits keep the last writer at the path. The loser is preserved as a
 `name.bdrive-conflict-<device>-<time>` file by the device that detects the
 overlap. Nothing is silently dropped.
 
+**Joining is an adoption, not a merge.** On a device's first sync of a project,
+a local file at a path the project already holds is not a concurrent edit — it
+is a folder that happened to contain the same path (a checkout of the same
+docs, an agent-written `AGENTS.md`, the `.bdriveignore` `bdrive init` seeds).
+The project's version wins on every device and no conflict copy is made. Your
+copy is still journaled and pushed as a superseded version of that path, so
+`bdrive restore --list <path>` can bring it back. `bdrive sync` reports these as
+`adopted`.
+
 ## The daemon
 
 A per-mount daemon scans the folder every few seconds and exchanges with the