trail: add resume command

[peyton-alt]

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

Summary

• add entire trail resume with trail context, checkpoint session listing, picker/default resume behavior, and --session / --checkpoint targeting
• reuse checkpoint restore logic from session resume and add agent-native resume launchers
• restore prompt/review metadata for checkpoint sessions and cover missing-local-state behavior with integration tests

Verification

• mise run check
• go test ./cmd/entire/cli/integration_test -tags=integration -run TestTrailResume_UsesCheckpointSessionsWhenLocalStateIsMissing -count=1
• real-trail smoke tests on trails with multi-session checkpoint metadata

---

Note

Medium Risk
Touches git checkpoint restore, branch checkout/worktree clashes, and foreground subprocess launches of external agent binaries; behavior is mostly delegated to existing resume strategy but the new trail/API path increases user-facing surface area.

Overview
Adds entire trail resume to resolve a trail (API), show trail/findings/checkpoint-session context, restore transcripts from the trail branch’s latest checkpoint metadata (even when local session state is gone), and either print resume commands or spawn the agent via new resume launchers.

Checkpoint resume plumbing is refactored so restore returns []strategy.RestoredSession (restoreByCheckpointID, restoreFromCurrentBranch, restoreResumeSessions) while display/launch stay separate—trail resume reuses the same restore path as entire resume. Branch checkpoint discovery can anchor on a named branch ref (local or origin/), not only HEAD.

Agents gain a ResumeLauncher interface, shared NewForegroundCommand, ResumeLauncherFor in the registry, and LaunchResumeCmd for Claude, Codex, Copilot, Droid, Gemini, OpenCode, and Pi. Restored sessions now carry kind/review prompt metadata, with richer prompt previews (sidecar → review prompt → transcript extraction, skipping injected instructions). Interactive trail flows prefer work sessions over review/investigation when choosing what to continue.

Coverage includes unit tests for trail resume UX/validation, an integration test for multi-session checkpoint listing and --session restore after clearing local state, and minor .gitignore entries.

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

[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 894aa84. Configure here.}

[cursor]

Trail resume skips agent launch

Medium Severity

entire trail resume restores via restoreByCheckpointID / restoreFromCurrentBranch, then only launches the agent when those helpers return a non-empty []RestoredSession. When metadata is fetched through checkRemoteMetadata (which finishes via resumeSession) or when restoreResumeSessions falls back to resumeSingleSession, restore succeeds and prints resume output but returns no session slice, so continueTrailRestoredSessions exits without launching the agent on interactive runs.

Additional Locations (2)

• cmd/entire/cli/resume.go#L933-L934
• cmd/entire/cli/trail_resume_cmd.go#L249-L251

 

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

[cursor]

Accidental test file committed

Low Severity

The diff adds t1.txt containing only test 1, which looks like scratch content unrelated to trail resume and should not ship in the repository.

 

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

[Copilot]

Pull request overview

Adds a new entire trail resume command that can show trail context plus checkpoint-backed session listings, then restore and (optionally) launch an agent-native resume flow. This builds on the existing resume/restore machinery by reusing checkpoint restore logic and enhancing restored session metadata (prompt/kind/review prompt) to improve selection and display.

Changes:

• Introduces entire trail resume with context output, interactive picker/default behavior, and --session / --checkpoint targeting.
• Reuses/refactors resume restore internals to return restored session slices and includes review metadata for better prompt previews.
• Adds agent “resume launchers” (subprocess-spawnable resume) plus unit/integration tests covering missing-local-state behavior.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
t1.txt	Adds a new text file (appears unrelated to this feature).
cmd/entire/cli/trail_resume_cmd.go	Implements entire trail resume command, context rendering, selection, restore, and optional agent launch.
cmd/entire/cli/trail_resume_cmd_test.go	Unit tests for option validation, context rendering/JSON encoding, and restored-session choice behavior.
cmd/entire/cli/trail_cmd.go	Registers the new trail resume subcommand.
cmd/entire/cli/strategy/strategy.go	Extends RestoredSession to carry kind/review prompt metadata.
cmd/entire/cli/strategy/rewind_test.go	Adds tests for restored prompt preview fallback; updates test agent to satisfy prompt extraction needs.
cmd/entire/cli/strategy/manual_commit_rewind.go	Improves restored prompt preview derivation (sidecar → review prompt → transcript-derived prompts).
cmd/entire/cli/resume.go	Refactors restore paths to return restored sessions so callers (like trail resume) can decide how to display/launch.
cmd/entire/cli/resume_picker.go	Adds shared unknownAgentLabel constant for consistent UI strings.
cmd/entire/cli/integration_test/trail_resume_test.go	Integration test ensuring checkpoint sessions are used when local session state is missing.
cmd/entire/cli/agent/registry.go	Adds ResumeLauncherFor to resolve agents that can be subprocess-launched for resume.
cmd/entire/cli/agent/registry_test.go	Tests ResumeLauncherFor.
cmd/entire/cli/agent/pi/pi.go	Adds LaunchResumeCmd for Pi agent.
cmd/entire/cli/agent/opencode/opencode.go	Adds LaunchResumeCmd for OpenCode agent.
cmd/entire/cli/agent/geminicli/gemini.go	Adds LaunchResumeCmd for Gemini CLI agent.
cmd/entire/cli/agent/factoryaidroid/factoryaidroid.go	Adds LaunchResumeCmd for Factory AI Droid agent.
cmd/entire/cli/agent/copilotcli/copilotcli.go	Adds LaunchResumeCmd for Copilot CLI agent.
cmd/entire/cli/agent/codex/codex.go	Adds LaunchResumeCmd for Codex agent.
cmd/entire/cli/agent/codex/codex_test.go	Adds a LaunchResumeCmd shape test (skips if binary missing).
cmd/entire/cli/agent/claudecode/claude.go	Adds LaunchResumeCmd for Claude Code agent.
cmd/entire/cli/agent/agent.go	Introduces the ResumeLauncher interface.
cmd/entire/cli/agent/foreground.go	Adds helper to build foreground-wired subprocess commands (NewForegroundCommand).
.gitignore	Ignores a few additional local artifact directories.

[pfleidi]

So far, we were outputting the CLI commands to resume a session. This left the decision when to resume to the user. I'm wondering if we need to update each agent to support immediately resuming the session. This adds additional complexity while making assumptions that might not be necessarily true. 🤔