attach: pasteable retry hint and export-install error cleanup - #2108
Open
gtrrz-victor wants to merge 2 commits into
Open
attach: pasteable retry hint and export-install error cleanup#2108gtrrz-victor wants to merge 2 commits into
gtrrz-victor wants to merge 2 commits into
Conversation
Three follow-ups to the OpenCode on-demand transcript fetch (#1877). unprobedFetcherHint told the user which --agent flag to add and left them to assemble the rest. It now prints the whole command on its own line, following the `\nHint:` convention in checkpoint_resume.go / explain.go, and spells the canonical `entire session attach` rather than the deprecated top-level form — TestNoDeprecatedCommandFormsInUserFacingStrings catches that, since a hint that trips the CLI's own deprecation warning is advice the CLI gave itself. A canceled fetch escaped the transcriptFetchError suppression, so Ctrl-C during `opencode export` got the secondary auto-detection failure appended to it. Wrap it, which is all the comment at the suppression branch ever claimed. renameOverExisting and its caller both said "failed to install export file", so a rename that could not land reported it twice in one message. fetchAndCacheExport keeps the wording — it is the one that also knows where the validated export was kept — and the rename passes os.Rename's error through raw, which already carries the operation, both paths, and the cause. Also documents TranscriptFetcher, the one optional agent capability with no entry in the integration docs. The load-bearing distinction: TranscriptPreparer refreshes a file that already exists, TranscriptFetcher conjures one that never did. Tests: the rename-failure path was uncovered. Both new cases force it with a directory at the destination, so they need no os.Rename stub and behave the same on every platform. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Entire-Checkpoint: 01M0SF9KXN72BA1AHHEEKJ3968
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the entire session attach experience when a transcript can be exported on-demand (via the new TranscriptFetcher capability), and cleans up OpenCode export-install error wording to avoid duplicate user-facing messages.
Changes:
- Add/describe the
TranscriptFetcheroptional agent interface and update integration guidance to recommend implementing it for attach-on-untracked sessions. - Improve
attachfailure messaging with a pasteable retry command when other agents can export transcripts on demand, while keeping auto-detection side-effect-free. - Adjust OpenCode export staging/install error propagation to prevent duplicated “failed to install export file” wording, with additional tests.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/architecture/agent-integration-checklist.md | Adds checklist guidance to implement TranscriptFetcher to support session attach for untracked sessions. |
| docs/architecture/agent-guide.md | Documents the TranscriptFetcher interface and its contract/usage expectations. |
| cmd/entire/cli/attach.go | Makes attach errors include a pasteable retry hint for fetch-capable agents; suppresses noisy auto-detect errors on canceled fetch. |
| cmd/entire/cli/attach_test.go | Updates/extends tests to assert pasteable retry hints and cancellation suppression behavior. |
| cmd/entire/cli/agent/opencode/stage_export.go | Removes duplicate wrapping so user-facing install wording is owned by the caller. |
| cmd/entire/cli/agent/opencode/lifecycle_test.go | Adds coverage ensuring failed installs preserve staged exports and produce non-duplicated messaging. |
| cmd/entire/cli/agent/opencode/cli_commands_test.go | Adds coverage ensuring renameOverExisting passes through raw os.Rename errors (caller owns wording). |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
gtrrz-victor
marked this pull request as ready for review
August 24, 2026 09:00
A canceled attach means the user asked to quit; probing every other agent's transcript locations after that is work nobody is waiting for. Return the context.Canceled error directly instead. Entire-Checkpoint: 01M0SGFEH1Q72EJRHJQVD5JG88
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
https://entire.io/gh/entireio/cli/trails/1130
This draft pull request was opened by Entire after CI was requested for the linked trail. Feel free to edit the title or body — the link above is what keeps the trail and PR connected.
Note
Low Risk
Error-message and wrapping tweaks plus tests/docs; no change to attach success path or export install semantics beyond who wraps the error.
Overview
Cleans up two user-facing attach failure paths.
When auto-detect cannot find a transcript, the hint for agents that can export on demand is now a pasteable
entire session attach <session> --agent …command (withe.g.only if more than one fetcher exists). A canceledFetchTranscriptis wrapped astranscriptFetchErrorso Ctrl-C is not followed by a noisy auto-detect failure.OpenCode’s
renameOverExistingno longer wraps non-contention rename errors;fetchAndCacheExportowns the “failed to install export file” wording so it appears once and still points at the preserved staging file. Docs add theTranscriptFetchercontract.Reviewed by Cursor Bugbot for commit 738611d. Configure here.