feat: adopt active sessions across repos and worktrees

[peyton-alt]

Trail: https://entire.io/gh/entireio/cli/trails/613/adopt-active-sessions-across-repos-and-worktrees

Summary

Adds entire session adopt [session-id] --from <source-worktree> so an active agent session can be explicitly anchored into the repo/worktree where the next commit is about to happen.

This addresses the case we hit where an agent session was tracked under one repo/worktree, but the agent made and committed changes in another repo. The target repo hooks can fire correctly, but without target-local session state the commit has no session to link and can miss the Entire-Checkpoint trailer.

What changed

• Adds the session adopt subcommand under entire session.
• Reads the source worktree session store from .git/entire-sessions.
• Supports explicit session ID, or a single recent active source session when no ID is provided.
• Rejects ended or fully condensed source sessions.
• Writes target-local session state using the target repo HEAD, branch, worktree path, and worktree ID.
• Keeps the original live transcript path because the transcript belongs to the continuing agent session.
• Seeds FilesTouched from current target repo changes.
• Warns that those current target changes will be attributed to the adopted session.
• Rejects adoption when source and target share the same git common dir, because that would overwrite the same session state file rather than copying between independent stores.
• Clears source-local checkpoint bookkeeping before saving target state.
• Resets the adopted checkpoint/transcript window (StepCount, transcript offset/size, transcript identifier, last checkpoint IDs) so long-running sessions do not inherit stale source-repo checkpoint state.
• Preserves cumulative turn/context metrics while anchoring the adopted prompt window at the current source turn count, so the first target checkpoint only counts target-side turns.
• Leaves AttachedManually false because adoption is not entire session attach.

This lets the target repo commit hooks find the adopted session by target worktree, pass the staged-file overlap check, add an Entire-Checkpoint trailer, and condense normally on post-commit.

Review fixes

Addressed the first four trail findings in follow-up commit aae06c4e100bf091dd305b222df469ee9cab4228:

• Added a warning for target-worktree file attribution.
• Documented why adopted sessions reset target-local checkpoint bookkeeping.
• Cleared AttachedManually for adopted active sessions.
• Added test coverage for the warning and attach-flag behavior.

Follow-up trailer: Entire-Checkpoint: b7f863b91041

After that, a new transcript-path finding was opened. The suggested behavior was not correct for cross-repo adoption, because the live transcript belongs to the continuing source agent session, not the target repo. Commit 9ffec38cf2fad2c962d48267aa9a1738358f0070 documents that intent in code.

Clarification trailer: Entire-Checkpoint: 0d316d428771

Commit 1cc4003cc15da8c821ca98657ae6a27730770107 resets adopted checkpoint/transcript window state and adds a regression test where the source session already had prior checkpoint state before adoption.

Window-reset trailer: Entire-Checkpoint: a946a346b0a7

Commit 86cb382b985235c877cc19f6174f1d52661ca969 rejects same-git-common-dir adoption and proves the existing source state is preserved.

Shared-store guard trailer: Entire-Checkpoint: c555c03f3864

Commit e6f63ebcf38630fa8bb9b61b33b801a0c65b5a84 anchors the adopted prompt window at the current source turn count while preserving cumulative session metrics, so long-running sessions do not inflate the target checkpoint prompt count.

Prompt-window anchor trailer: Entire-Checkpoint: 6fb8304acd8d

Commit dd22ba19819221df5250e041a491e988f8c414d1 clears deprecated legacy transcript offset fields whenever adoption resets the checkpoint transcript window, and adds a regression that proves those stale JSON fields are not re-persisted.

Legacy-offset trailer: Entire-Checkpoint: db8b4bffc8b4

Commit and checkpoint verification

• 6add2bae652a5983fe0ffe9171e92710051714c5 - Entire-Checkpoint: 7fb3d4d78c7f
• aae06c4e100bf091dd305b222df469ee9cab4228 - Entire-Checkpoint: b7f863b91041
• 9ffec38cf2fad2c962d48267aa9a1738358f0070 - Entire-Checkpoint: 0d316d428771
• 1cc4003cc15da8c821ca98657ae6a27730770107 - Entire-Checkpoint: a946a346b0a7
• 86cb382b985235c877cc19f6174f1d52661ca969 - Entire-Checkpoint: c555c03f3864
• e6f63ebcf38630fa8bb9b61b33b801a0c65b5a84 - Entire-Checkpoint: 6fb8304acd8d
• dd22ba19819221df5250e041a491e988f8c414d1 - Entire-Checkpoint: db8b4bffc8b4

Push output confirmed entire/checkpoints/v1 synced to the checkpoint remote.

Real smoke test

Ran a disposable cross-repository smoke test with two separate temp git repos.

Flow:

1. Built the local CLI from this branch.
2. Created a source repo with a fake active Claude Code session and transcript.
3. Created a separate target repo with src/feature.go staged.
4. Ran entire session adopt smoke-adopt-session-001 --from <source> --force in the target repo.
5. Verified adopt output tracked src/feature.go.
6. Ran the real hooks git prepare-commit-msg handler.
7. Verified it added Entire-Checkpoint: 08f656dbcb95.
8. Committed and ran hooks git post-commit.
9. Verified the committed message retained the trailer and post-commit state referenced that checkpoint.

Smoke result:

SMOKE_OK root=/private/tmp/entire-adopt-smoke-qkoNM8
adopt_output=Adopted session smoke-ad from /private/tmp/entire-adopt-smoke-qkoNM8/source
Tracking 1 file(s): src/feature.go
checkpoint=08f656dbcb95
commit=85a17c3
commit_message=smoke adopt||Entire-Checkpoint: 08f656dbcb95

Tests

• go test ./cmd/entire/cli -run TestSessionAdopt_CopiesExternalSessionIntoCurrentWorktree -count=1
• go test ./cmd/entire/cli -run TestSessionAdopt -count=1
• go test ./cmd/entire/cli -count=1
• mise run lint
• mise run check

Latest verification after dd22ba19819221df5250e041a491e988f8c414d1: mise run check passed, including lint, integration tests, Vogon canary, and roger-roger canary.

Caveats

This is explicit adoption, not automatic discovery. Agents or users should run it from the target repo/worktree before committing, and the source transcript path must still be readable on the same machine.

Adoption now intentionally rejects source/target worktrees that share the same git common dir. Those sessions share one .git/entire-sessions store; copying adoption state there would mutate the original live session instead of creating independent target-local state. Same-repo sibling worktree matching should be handled by the sibling-worktree matching path instead.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, 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 6add2ba. Configure here.}

[Copilot]

Pull request overview

This PR adds an explicit entire session adopt subcommand to copy (“adopt”) an in-progress agent session that’s currently tracked under a different repo/worktree into the current repo/worktree so the commit hooks can find local session state and reliably add an Entire-Checkpoint trailer.

Changes:

• Add entire session adopt [session-id] --from <source-worktree> command wiring under the session group.
• Implement adoption logic that locates the source worktree’s .git/entire-sessions, selects an adoptable session, and writes a target-local session state seeded with current file changes.
• Add unit tests covering cross-repo adoption, source resolution from a nested path, and PrepareCommitMsg trailer insertion after adoption.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
cmd/entire/cli/sessions.go	Adds the adopt subcommand to session help text and registers the command.
cmd/entire/cli/session_adopt.go	Implements the adopt command, source store resolution, session selection, and target-local state writing.
cmd/entire/cli/session_adopt_test.go	Adds tests for adoption behavior and hook trailer behavior after adoption.