fix(session): claim source on deferred cross-common-dir adopt to prevent double-adopt

The deferred cross-common-dir auto-adopt (DeferSourceRetire) registers the
adopted session in the target and stamps PendingSourceRetire, but left the
source session untouched at prepare time. Two targets that concurrently
discover the same unique live source could both pass the exactly-one-candidate
check, acquire the shared source lock in turn, and each register their own copy
of the same SessionID — a double-adopt, because neither wrote anything the other
would observe. The in-band tombstone the deferral removed had provided that
cross-process mutual exclusion.

Restore it without re-tombstoning at prepare time: under the same source-common-
dir lock, stamp a non-destructive AdoptClaim (target common dir + timestamp) on
the source. It does not end the session, so the source agent keeps checkpointing
(preserving the deferral's abort-safety). A second concurrent adopt re-reads the
source under the lock, observes a fresh claim by a different target, and refuses
(sourceClaimedError -> auto-adopt skips). The candidate discovery filter drops a
claimed source too. post-commit finalize's retire supersedes the claim; a claim
older than adoptRecentWindow is ignored, so an abandoned claim from an aborted
commit self-heals. A re-claim by the same target is idempotent.

Entire-Checkpoint: 01KYX128X8JKV7FH75QR1FV8NW

Author: suhaanthayyil

cmd/entire/cli/session/state.go

@@ -143,6 +143,20 @@ type State struct {
 	// (finalizePendingSourceRetires). nil in the normal steady state.
 	PendingSourceRetire *PendingSourceRetire `json:"pending_source_retire,omitempty"`
 
+	// AdoptClaim is a non-destructive, in-flight cross-common-dir adoption
+	// marker written on the SOURCE session at prepare-commit-msg time when the
+	// destructive retire is deferred to post-commit (DeferSourceRetire). It is
+	// what restores the cross-process mutual exclusion the in-band tombstone used
+	// to provide: a second target that concurrently discovers the same unique
+	// candidate observes a FRESH claim by a different common dir and skips, so the
+	// session is never double-adopted. Unlike a tombstone it does NOT end the
+	// session — the source agent keeps checkpointing, preserving the abort-safety
+	// of the deferral. Superseded by finalizePendingSourceRetires' retire. A claim
+	// older than the adopt-recency window is ignored, so an abandoned claim (an
+	// aborted commit that never reached post-commit) self-heals and frees the
+	// source for a later legitimate adopt. nil in the normal steady state.
+	AdoptClaim *AdoptClaim `json:"adopt_claim,omitempty"`
+
 	// Branch is the git branch HEAD pointed at the last time this session took a
 	// turn. Captured on each turn start so it tracks branches created or renamed
 	// after the session began. Empty when HEAD was detached or for sessions
@@ -391,6 +405,22 @@ type PendingSourceRetire struct {
 	SourceWorktreePath string `json:"source_worktree_path,omitempty"`
 }
 
+// AdoptClaim stamps a source session as being adopted, in-flight, by a specific
+// target worktree while its destructive retire is deferred to post-commit. It is
+// the lightweight lock marker that a concurrent adopter must observe to avoid
+// double-adopting the same unique session across processes. See State.AdoptClaim.
+type AdoptClaim struct {
+	// ByCommonDir is the git common dir of the TARGET worktree that claimed this
+	// source. A claim by a *different* common dir blocks a new adoption; a
+	// re-claim by the same common dir is idempotent (re-adopt is fine).
+	ByCommonDir string `json:"by_common_dir"`
+	// ByWorktreePath is the target worktree root (best-effort, for logging).
+	ByWorktreePath string `json:"by_worktree_path,omitempty"`
+	// At is when the claim was written. A claim older than the adopt-recency
+	// window is treated as abandoned (aborted commit) and no longer blocks.
+	At time.Time `json:"at"`
+}
+
 // PromptAttribution captures line-level attribution data at the start of each prompt.
 // By recording what changed since the last checkpoint BEFORE the agent works,
 // we can accurately separate user edits from agent contributions.

cmd/entire/cli/session_adopt.go

@@ -171,6 +171,14 @@ func adoptFromExternalSessionStore(
 		if !isAdoptableSourceSession(sourceState) {
 			return fmt.Errorf("session %s is ended or fully condensed and cannot be adopted", sessionID)
 		}
+		// Cross-process mutual exclusion for the deferred (auto-adopt) path. The
+		// shared sourceCommonDir lock serializes two concurrent adopts of the same
+		// unique candidate; this makes the loser OBSERVE the winner's claim and
+		// refuse, so the session is adopted into exactly one repo. A stale claim
+		// (aborted commit) or a re-claim by this same target does not block.
+		if opts.DeferSourceRetire && adoptClaimBlocks(sourceState.AdoptClaim, targetCommonDir) {
+			return &sourceClaimedError{sessionID: sessionID, claimedBy: adoptClaimLabel(sourceState.AdoptClaim)}
+		}
 		if !sessionBelongsToSourceWorktree(sourceState, sourceWorktree, sourceWorktreeID) {
 			return fmt.Errorf("session %s belongs to %s, not %s",
 				sessionID, adoptSessionWorktreeLabel(sourceState), sourceWorktree)
@@ -209,7 +217,26 @@ func adoptFromExternalSessionStore(
 			return fmt.Errorf("save adopted session state: %w", err)
 		}
 		if opts.DeferSourceRetire {
-			// Non-destructive prepare phase: target registered, source untouched.
+			// Non-destructive prepare phase: stamp a claim on the SOURCE (under the
+			// shared source lock) so a concurrent adopt by a different target sees
+			// it and skips, then leave the source otherwise ACTIVE so it keeps
+			// checkpointing until post-commit finalizes the retire. The claim is
+			// recency-bounded, so an aborted commit (no post-commit) self-heals once
+			// it ages out.
+			sourceState.AdoptClaim = &session.AdoptClaim{
+				ByCommonDir:    targetCommonDir,
+				ByWorktreePath: next.WorktreePath,
+				At:             time.Now(),
+			}
+			if err := sourceStore.Save(ctx, sourceState); err != nil {
+				// Roll back the target registration so a failed claim never leaves a
+				// claimless double-adopt window. Use a non-cancelable context for the
+				// same reason the retire path does (the caller's ctx may be timed out).
+				if rollbackErr := rollbackExternalAdoptTarget(context.WithoutCancel(ctx), targetStore, next.SessionID, existing); rollbackErr != nil {
+					return &adoptRollbackFailedError{retireErr: err, rollbackErr: rollbackErr}
+				}
+				return fmt.Errorf("claim source session state: %w", err)
+			}
 			adopted = next
 			filesTouched = touched
 			return nil
@@ -276,6 +303,8 @@ func retireAdoptedSourceSession(source, target *session.State) session.State {
 	retired.FilesTouched = nil
 	retired.TurnID = ""
 	retired.TurnCheckpointIDs = nil
+	// The tombstone supersedes any in-flight adoption claim on the source.
+	retired.AdoptClaim = nil
 	retired.AdoptedIntoWorktreePath = target.WorktreePath
 	retired.AdoptedIntoWorktreeID = target.WorktreeID
 	return retired
@@ -515,6 +544,51 @@ func isAdoptableSourceSession(state *session.State) bool {
 		!state.FullyCondensed
 }
 
+// adoptClaimBlocks reports whether a source session's in-flight adoption claim
+// should block a NEW deferred adoption by targetCommonDir. A claim blocks only
+// when it is (a) present, (b) FRESH — within the adopt-recency window, so a stale
+// claim left by an aborted commit self-heals rather than pinning the source
+// forever — and (c) held by a DIFFERENT common dir, since a re-adopt by the same
+// target is idempotent. Reuses adoptRecentWindow (= session.LiveSessionMaxAge);
+// no separate TTL is introduced.
+func adoptClaimBlocks(claim *session.AdoptClaim, targetCommonDir string) bool {
+	if claim == nil || claim.At.IsZero() {
+		return false
+	}
+	if time.Since(claim.At) > adoptRecentWindow {
+		return false
+	}
+	return !sameAdoptStore(claim.ByCommonDir, targetCommonDir)
+}
+
+func adoptClaimLabel(claim *session.AdoptClaim) string {
+	if claim == nil {
+		return unknownPlaceholder
+	}
+	if claim.ByWorktreePath != "" {
+		return claim.ByWorktreePath
+	}
+	if claim.ByCommonDir != "" {
+		return claim.ByCommonDir
+	}
+	return unknownPlaceholder
+}
+
+// sourceClaimedError is returned by adoptFromExternalSessionStore when the source
+// session already carries a FRESH cross-common-dir adoption claim by a DIFFERENT
+// target — a concurrent commit is mid-adopt of the same unique session. It is a
+// benign "lost the race" outcome that preserves adopt-exactly-once, not
+// corruption, so auto-adopt logs it at Debug and moves on rather than warning.
+type sourceClaimedError struct {
+	sessionID string
+	claimedBy string
+}
+
+func (e *sourceClaimedError) Error() string {
+	return fmt.Sprintf("session %s is already claimed for cross-common-dir adoption by %s",
+		e.sessionID, e.claimedBy)
+}
+
 func sessionLastSeen(state *session.State) time.Time {
 	if state.LastInteractionTime != nil {
 		return *state.LastInteractionTime
@@ -570,6 +644,9 @@ func buildAdoptedSessionState(ctx context.Context, source *session.State) (*sess
 	adopted.WorktreeID = worktreeID
 	adopted.AdoptedIntoWorktreePath = ""
 	adopted.AdoptedIntoWorktreeID = ""
+	// AdoptClaim is a source-side marker; the adopted (target) copy never carries
+	// one. The caller re-stamps it on the source under the shared lock.
+	adopted.AdoptClaim = nil
 	adopted.Branch = branch
 	adopted.LastInteractionTime = &now
 	adopted.Phase = session.PhaseActive
@@ -631,6 +708,10 @@ func cloneAdoptSourceState(source *session.State) session.State {
 		pending := clonePromptAttribution(*source.PendingPromptAttribution)
 		adopted.PendingPromptAttribution = &pending
 	}
+	if source.AdoptClaim != nil {
+		claim := *source.AdoptClaim
+		adopted.AdoptClaim = &claim
+	}
 	return adopted
 }
 

cmd/entire/cli/session_auto_adopt.go

@@ -188,14 +188,23 @@ func tryAutoAdoptCrossCommonDirSession(ctx context.Context) {
 	adoptCancel()
 	if adoptErr != nil {
 		var rollbackFailed *adoptRollbackFailedError
-		if errors.As(adoptErr, &rollbackFailed) {
+		var claimed *sourceClaimedError
+		switch {
+		case errors.As(adoptErr, &rollbackFailed):
 			// Retire failed AND rollback failed: the session is now registered in
 			// both the source and target repos. This is corruption, not a miss.
 			logging.Error(logCtx, "auto-adopt: adopt left session registered in both repos",
 				slog.String("session_id", source.SessionID),
 				slog.String("error", adoptErr.Error()),
 			)
-		} else {
+		case errors.As(adoptErr, &claimed):
+			// Lost the concurrent-adopt race: another target claimed this source
+			// first, under the shared source lock. Adopt-exactly-once is preserved,
+			// so this is an expected skip, not a failure.
+			logging.Debug(logCtx, "auto-adopt: source already claimed by a concurrent adopt",
+				slog.String("session_id", source.SessionID),
+			)
+		default:
 			logging.Warn(logCtx, "auto-adopt: adopt failed",
 				slog.String("session_id", source.SessionID),
 				slog.String("error", adoptErr.Error()),
@@ -396,7 +405,7 @@ func collectRegistryAutoAdoptCandidates(
 		// alone therefore cannot steal across unrelated repos.
 		resolved++
 		resolveCtx, resolveCancel := context.WithTimeout(ctx, autoAdoptGitResolveTimeout)
-		cand, ok := candidateFromSource(resolveCtx, entry.WorktreePath, entry.SessionID, staged, owner, hasOwner)
+		cand, ok := candidateFromSource(resolveCtx, entry.WorktreePath, entry.SessionID, targetCommonDir, staged, owner, hasOwner)
 		resolveCancel()
 		if ok {
 			out = append(out, cand)
@@ -456,7 +465,7 @@ func collectSiblingAutoAdoptCandidates(
 			if !isRecentAdoptCandidate(state) {
 				continue
 			}
-			cand, ok := candidateFromLoaded(store, worktree, commonDir, state, staged, owner, hasOwner)
+			cand, ok := candidateFromLoaded(store, worktree, commonDir, targetCommonDir, state, staged, owner, hasOwner)
 			if ok {
 				out = append(out, cand)
 			}
@@ -468,6 +477,7 @@ func collectSiblingAutoAdoptCandidates(
 func candidateFromSource(
 	ctx context.Context,
 	sourceWorktree, sessionID string,
+	targetCommonDir string,
 	staged []string,
 	owner proclive.Identity,
 	hasOwner bool,
@@ -480,12 +490,13 @@ func candidateFromSource(
 	if err != nil || state == nil {
 		return autoAdoptCandidate{}, false
 	}
-	return candidateFromLoaded(store, worktree, commonDir, state, staged, owner, hasOwner)
+	return candidateFromLoaded(store, worktree, commonDir, targetCommonDir, state, staged, owner, hasOwner)
 }
 
 func candidateFromLoaded(
 	store *session.StateStore,
 	worktree, commonDir string,
+	targetCommonDir string,
 	state *session.State,
 	staged []string,
 	owner proclive.Identity,
@@ -494,6 +505,14 @@ func candidateFromLoaded(
 	if !isRecentAdoptCandidate(state) {
 		return autoAdoptCandidate{}, false
 	}
+	// A source already carrying a FRESH adoption claim by a DIFFERENT target is
+	// mid-adopt by another commit; drop it so this commit does not double-adopt.
+	// Our own claim (same common dir) and a stale claim (aborted commit) do not
+	// exclude. This is the best-effort discovery-time skip; the authoritative
+	// serialization is the under-lock claim check in adoptFromExternalSessionStore.
+	if adoptClaimBlocks(state.AdoptClaim, targetCommonDir) {
+		return autoAdoptCandidate{}, false
+	}
 	// Auto-adopt is ACTIVE-only (matches the live-registry prefilter; see
 	// docs/architecture/sessions-and-checkpoints.md, "Automatic cross-common-dir
 	// adoption").