Let a session follow its agent into the worktree it commits in

[peyton-alt]

https://entire.io/gh/entireio/cli/trails/1378

Users working across worktrees had to run entire session attach because their commits weren't linked. This happened whenever an agent was launched in the main checkout and then worked in a worktree. The cause: a session is homed once, where its first turn-start hook ran, and never moves. Hooks run where the agent was launched, so the session's home and the actual work diverge. Commit linking then relied on process ancestry to find the session, silently refused when several worktrees had live sessions, and pointed users at session adopt, which moves a live session.

This PR makes the session follow its agent between worktrees of one repository.

Split out: idle-session survival is #2573, squash trailer retention is #2574, and redo (reset) trailer retention is #2582.

Changes

The session follows its agent's commits. When a commit in another worktree condenses the session that process ancestry identified, the session is re-homed there. The exception is when the old home still holds pending content (rehomeSessionAfterOwnCommit).

The trailer identifies its sessions.

• prepare-commit-msg reserves the stamped checkpoint ID on each session, once the message write has succeeded.
• post-commit then links the commit through that reservation even when paths and ancestry differ between the two hooks (reserveCheckpointForStampedSessions, sessionsIncludingReservedFor).

Refusals are visible. When linking declines, it names the candidate sessions and worktrees on the terminal, with session attach as the remedy (announceUnlinkedCommit). This only runs from prepare-commit-msg.

The hook follows the agent's working directory.

• Agents report where they work on every hook payload (Event.CWD). Claude Code, Codex, Copilot, Factory Droid and pi all send one.
• When it names another worktree of the same repository where Entire is enabled, the hook process moves there before resolving anything, and its log sink moves with it (followAgentWorkingDirectory).
• Turn start and turn end then re-home the session, so no process ancestry is needed. This also covers Windows, where ancestry can't be read.
• Re-homing happens only on a strong signal: a turn boundary whose payload named the tree, or edits captured there. A hook without a cwd never pulls a session back.

An identified agent's commit links only its own session. When process ancestry names the committing agent, the other-worktree fallback is skipped and only sessions actually homed in the commit's worktree join it. Several agents launched from one checkout, each in its own worktree, are all still homed in that checkout until their first turn ends, so the fallback used to give one agent's mid-turn commit to all of them.

Subagents and tool use follow too, without mis-attributing work. A turn or task can start in one worktree and end in another.

• End hooks find the pre-prompt and pre-task baselines where the turn started (SessionState.TurnWorktreePath) or at the session's home, and consume them there (state_baseline.go).
• Only this turn's prompt.txt entry is carried over; earlier turns' prompts stay with the steps saved at home.
• A baseline from another tree can't tell that tree's pre-existing untracked files from new ones. New-file detection then falls back to the transcript, the same as when the untracked scan is skipped. Files created only by shell commands the transcript never names are missed rather than wrongly claimed.
• MutateSessionState records the hook's worktree whenever a mutation adds files or task records (PendingContentWorktree). Pending work recorded in the tree the session moves to no longer pins it to its old home; shadow-branch steps still always do.
• A turn end that saved no step, such as a subagent-only turn, re-homes as well.

session attach and session adopt behave as before. Adopt now records the carried-over content as pending in the target worktree.

Testing

• Integration tests for every re-home path:
  • own commit;
  • payload cwd;
  • signal-less hooks in the launch directory;
  • agents without a cwd;
  • a mid-turn move, including which prompt is carried;
  • a task that crosses trees;
  • a task entirely in the worktree;
  • Codex tool-use files recorded in the worktree and in both trees.
• Three agents launched from main, each committing in its own worktree X, Y, Z (real binary, the commit made under the agent's own process): Y's checkpoint now holds only Y's session, mid-turn and after a turn, with the agents editing the same or different paths. main condenses all three sessions into it.
• Unit tests for the follower's decisions, the location-aware guard, Droid/Copilot cwd parsing, and adopt.
• mise run check green.
• A real-binary scenario with installed git hooks, fresh multi-worktree repos and detached hooks with no agent ancestry. 17 checks across Claude Code (mid-turn move, cross-tree task, worktree-only task, both-tree guard, no-cwd guard) and Factory Droid all pass on this head; 9 of them fail on the pre-fix binary.

Follow-ups

• Agents that send no working directory still rely on own-commit and captured-edit re-homing: Cursor (only workspace_roots), OpenCode and the external-agent protocol. OpenCode child sessions and an external-protocol cwd field are tracked separately.
• An interactive chooser for a human committing in a third tree.
• A commit with no terminal and no agent ancestry (a GUI client or a script) is still treated as an agent commit: the fallback's candidates all condense into it. Restricting that changes how those commits link, so it is a separate change.
• Antigravity (merged since) sends no working directory, so it relies on own-commit re-homing like Cursor and OpenCode.

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

Five moderate findings remain unresolved in reservation, cleanup, portability, and re-homing behavior.

Pull request overview

This PR improves session linking across Git worktrees, including re-homing, trailer-based recovery, and safer cleanup.

Changes:

• Re-homes sessions after agent commits in foreign worktrees.
• Reserves checkpoint IDs for reliable post-commit linking.
• Preserves live idle sessions and improves ambiguity guidance.
• Adds documentation and integration coverage.

File summaries

File	Summary
docs/development/checkpoint-implementation.md	Documents implementation behavior.
docs/architecture/sessions-and-checkpoints.md	Documents cross-worktree session behavior.
cmd/entire/cli/strategy/session_rehome_test.go	Tests re-homing guards.
cmd/entire/cli/strategy/session_identity.go	Implements linking and re-homing logic. Moderate finding: consumed files can prevent re-homing.
cmd/entire/cli/strategy/session_identity_test.go	Tests linking announcements.
cmd/entire/cli/strategy/manual_commit_test.go	Tests cleanup behavior. Moderate finding: cleanup expectation is not portable.
cmd/entire/cli/strategy/manual_commit_session.go	Updates orphan detection. Moderate finding: pending reservations may be deleted.
cmd/entire/cli/strategy/manual_commit_hooks.go	Adds trailer reservation and post-commit handling. Two moderate findings concern stale or uncancellable reservations.
cmd/entire/cli/integration_test/worktree_rehome_test.go	Tests foreign-worktree re-homing.
cmd/entire/cli/integration_test/testenv.go	Supports linked-worktree commit-message files.
cmd/entire/cli/integration_test/session_state_idle_survives_test.go	Tests idle-session preservation.
cmd/entire/cli/integration_test/postcommit_reserved_trailer_test.go	Tests reserved-trailer recovery.

Review details

Suppressed comments (5)

cmd/entire/cli/strategy/manual_commit_hooks.go:522

• The reservation is persisted before the commit-message write below. If os.WriteFile fails, this hook returns nil and Git can still create the commit without the trailer, leaving a pending checkpoint ID that no commit names; a later commit can then reuse that stale reservation. Move this call until after the message write succeeds, as addTrailerForAgentCommit already does.

	reserveCheckpointForStampedSessions(ctx, sessionsWithContent, checkpointID)

cmd/entire/cli/strategy/manual_commit_hooks.go:522

• This persists a CondensationAttempt before the message is written, but the no-trailer path in PostCommit returns without clearing it when the user removes the trailer (the documented opt-out flow). The next turn/doctor can then reuse or condense this reserved ID even though the user explicitly declined linkage, so the reservation needs a durable way to be cancelled when its stamped trailer is absent while still preserving genuine interrupted condensations.

	reserveCheckpointForStampedSessions(ctx, sessionsWithContent, checkpointID)

cmd/entire/cli/strategy/manual_commit_session.go:195

• The orphan predicate does not account for PendingCondensationID(). A newly stamped session can therefore be IDLE, have no shadow branch or task records, and be deleted as soon as its owner exits (or a later hook observes it), losing the reserved checkpoint that the new trailer-based recovery depends on. Pending condensation attempts should be retained or handled through the recovery path before applying this owner-exited cleanup.

func isOrphanedSessionState(state *SessionState) bool {
	if state.Phase.IsActive() || !state.LastCheckpointID.IsEmpty() || state.HasTaskContent() {
		return false
	}
	if state.Phase == session.PhaseIdle {
		return state.OwnerExited()

cmd/entire/cli/strategy/manual_commit_test.go:391

• This test is not portable to the platforms supported by proclive: proc_other.go makes OwnerLiveness unknown there, so idleDeadOwner.OwnerExited() is false and isOrphanedSessionState correctly keeps this state. The test nevertheless unconditionally requires idle-dead-owner to have been deleted, causing failures on Windows and other unsupported platforms. Make the expected cleanup conditional on the owner check, just as the live-owner fixture already is.

	// Verify stale sessions were actually cleared from disk
	for _, staleID := range []string{"idle-dead-owner", "stale-ended"} {

cmd/entire/cli/strategy/session_identity.go:176

• postCommitProcessSessionLocked's guest-condensation path intentionally leaves FilesTouched in the state while it preserves the home worktree (see manual_commit_hooks.go:1585-1593). Therefore, after a normal foreign-worktree commit has successfully condensed, this guard still sees the files just consumed and returns false, so sessions with tracked-file content are never re-homed and later non-agent commits remain ambiguous. Distinguish files still pending in the old home from files consumed by this commit (for example, carry that pre/post-condensation fact or compare with the committed file set) before applying this guard, and update the consumed list when the move succeeds.

	if len(state.FilesTouched) > 0 || state.StepCount > 0 || state.HasTaskContent() {

• Files reviewed: 12/12 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit deeab2b. Configure here.}

[cursor]

Rehome keeps stale attribution snapshots

Medium Severity

rehomeSessionAfterOwnCommit moves BaseCommit and realigns the attribution base after a guest condensation, but leaves PendingPromptAttribution and PromptAttributions in place. Turn-start always records that snapshot against the old home, and guest condensation already includes it when attributing the commit. The home condensation path clears both fields after a base move because those values have been consumed; without the same reset, the next SaveStep or condensation on the new home reapplies old-home user-line counts.

Additional Locations (1)

• cmd/entire/cli/strategy/manual_commit_hooks.go#L1615-L1619

 

^{Reviewed by Cursor Bugbot for commit deeab2b. Configure here.}