trail resume: finish the non-interactive contract

[peyton-alt]

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

entire trail resume was designed interactive-first; for agent callers (the most common caller) the non-interactive path was never finished. This PR completes it without touching the core semantics — checkpoint discovery, restore, and interactive launch all stay as they are.

Breaking for scripts: resume commands (trail resume, session resume, checkpoint resume) now exit non-zero whenever nothing was resumed; callers that relied on exit 0 in those cases must update. Interactive prompt declines still exit zero.

What changed

Never block, never need --force to complete. The older-checkpoint confirmation (promptResumeFromOlderCheckpoint) fired without a CanPromptInteractively() guard, so any branch with commits newer than its last checkpoint hard-failed non-interactive runs — teaching agents to always pass --force, a flag that also overwrites local session logs. Non-interactive runs now proceed from the latest checkpoint with a one-line notice; --force regains its single meaning.

Honest exit codes. Every "nothing was resumed" path exited 0: the worktree clash, the no-checkpoint branch, and three metadata-unavailable paths in checkRemoteMetadata. All now return errors. Interactive user declines remain exit 0 by design (unreachable for agents).

Typed errors. ResumeWorktreeClashError (carries the other worktree's path), ResumeNoCheckpointError, ResumeMetadataUnavailableError — recoverable via errors.As through SilentError, so orchestrators can act on failures instead of parsing stderr.

Slim act path. Actually resuming no longer prints the trail header, session table, findings tables, and command menu (that's trail show/trail finding's job — and the act path skips those fetches entirely). Output is now: identity line, actions taken, and the default session's resume command as the final stdout line, machine-liftable. --no-resume keeps the full inspection dump.

--json action report. --json now composes with real resumes: trail, actions (fetched/switched, checkpoint id, commits behind HEAD), restored sessions, and a structured continuation (agent + session_id as fields). Typed failures emit the report with an error object and exit non-zero; pre-action failures keep empty stdout + stderr text. --no-resume --json is unchanged.

Idempotency pinned. Agents retry; a repeated resume is a clean no-op success, now guarded by an integration test.

entire session resume shares the restore engine and picks up the prompt guard and exit-code fixes; its tests are updated accordingly.

Companion PR (independent, also off main): trail show --json.

Testing

• Unit (7277), integration (380), and full Vogon canary all green
• New unit tests pin the prompt-guard notice, typed-error round-trips, worktree-clash error, slim-output contract, and JSON report shape
• Updated integration + e2e tests that previously pinned exit-0-on-nothing-resumed

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes CLI exit semantics and resume output for automation; core restore logic is mostly unchanged but agents and scripts may depend on the old exit-0-on-partial-failure behavior.

Overview
Completes the non-interactive contract for entire trail resume (and shared entire session resume restore paths) so agent callers get predictable behavior without leaning on --force.

Exit codes and typed failures. Paths that previously returned success with nothing restored now fail with ResumeNoCheckpointError, ResumeMetadataUnavailableError, and ResumeWorktreeClashError, recoverable via errors.As (including through SilentError). Integration and e2e tests now expect non-zero when no checkpoint exists or metadata cannot be loaded.

Non-interactive older checkpoints. When HEAD is ahead of the last checkpoint and there is no TTY, resume proceeds with a one-line notice instead of blocking on promptResumeFromOlderCheckpoint, so agents do not need --force just to avoid prompts.

Trail resume UX. The act path drops the full inspection dump (sessions/findings/menus); it prints a short identity line, restore summary, and the default session’s resume command as the final stdout line. --json works for real resumes (action report with continuation fields); typed failures include an error object in JSON. --no-resume --json stays the rich context dump.

Idempotency. New integration test TestResume_RerunIsIdempotent guards that repeating resume on the same branch stays a clean success.

^{Reviewed by Cursor Bugbot for commit 800b6d5. 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 800b6d5. Configure here.}

[Copilot]

Pull request overview

This PR completes the non-interactive contract for entire trail resume (and the shared entire session resume restore path) by making non-interactive runs never block on prompts, returning non-zero when nothing is resumed, adding typed resume errors, and introducing a --json action report for the act path.

Changes:

• Make resume “honest” for automation: non-interactive older-checkpoint confirmation is guarded, and “nothing resumed” paths now return typed errors (non-zero exit).
• Add trail resume --json act-path action report (including typed error objects on failure), while keeping --no-resume --json as the richer inspection payload.
• Update/expand unit, integration, and E2E tests to pin the new output and exit-code semantics (including idempotent reruns).

Reviewed changes

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

Show a summary per file

File	Description
e2e/tests/resume_test.go	Updates E2E expectations to require non-zero exit when no checkpoint exists.
cmd/entire/cli/trail_resume_output_test.go	Adds unit tests pinning the slim non-interactive stdout contract (final line is bare resume command).
cmd/entire/cli/trail_resume_json.go	Introduces --json act-path report generation, typed-error mapping, and best-effort “actions” fields.
cmd/entire/cli/trail_resume_json_test.go	Adds unit tests for JSON report shape, preferred-session selection, and typed-error mapping.
cmd/entire/cli/trail_resume_cmd.go	Reworks trail resume act vs inspection paths; adds identity line, slim continuation display, JSON act path, and typed worktree-clash error.
cmd/entire/cli/trail_resume_cmd_test.go	Updates option validation tests to allow --json without --no-resume.
cmd/entire/cli/resume.go	Adds prompt guard for non-interactive older-checkpoint cases; returns typed errors for no-checkpoint and metadata-unavailable paths.
cmd/entire/cli/resume_test.go	Updates unit tests to assert typed errors (no checkpoint, metadata unavailable).
cmd/entire/cli/resume_errors.go	Adds typed resume error types (ResumeWorktreeClashError, ResumeNoCheckpointError, ResumeMetadataUnavailableError).
cmd/entire/cli/resume_errors_test.go	Adds tests ensuring typed errors survive wrapping and that key failure paths return typed errors.
cmd/entire/cli/integration_test/resume_test.go	Updates integration tests for new non-zero exit semantics and adds idempotency coverage.
cmd/entire/cli/git_operations_test.go	Minor test update to reuse shared test branch constant.