Confirm before session attach links, and link any commit by whether it's pushed

api/checkpoint/metadata.go

@@ -151,6 +151,14 @@ type WriteOptions struct {
 	// CheckpointSummary.CommitSHA point back here.
 	CommitSHA string
 
+	// LinkedCommits links this checkpoint to existing commits without a
+	// trailer, as `entire session attach --commit` writes when the commit
+	// cannot be amended. Unlike the import anchor (CommitSHA) it is an
+	// attributing link: readers treat each entry exactly like a commit
+	// carrying this checkpoint's Entire-Checkpoint trailer. A rewrite of the
+	// same checkpoint keeps the existing entries and adds new ones.
+	LinkedCommits []LinkedCommit
+
 	// Transcript is the session transcript content (full.jsonl).
 	// Must be pre-redacted (via redact.JSONLBytes or redact.AlreadyRedacted for trusted sources).
 	Transcript redact.RedactedBytes
@@ -355,6 +363,10 @@ type CheckpointInfo struct {
 	// CheckpointID is the stable 12-hex-char identifier
 	CheckpointID id.CheckpointID
 
+	// LinkedCommits are the checkpoint's trailer-less commit links; see
+	// WriteOptions.LinkedCommits.
+	LinkedCommits []LinkedCommit
+
 	// SessionID is the session identifier (most recent session for multi-session checkpoints)
 	SessionID string
 
@@ -591,6 +603,8 @@ type CheckpointSummary struct {
 	FilesTouched     []string           `json:"files_touched"`
 	Sessions         []SessionFilePaths `json:"sessions"`
 	TokenUsage       *types.TokenUsage  `json:"token_usage,omitempty"`
+	// LinkedCommits: attributing trailer-less links; see WriteOptions.LinkedCommits.
+	LinkedCommits []LinkedCommit `json:"linked_commits,omitempty"`
 
 	// LegacyCombinedAttribution carries the combined_attribution older CLIs
 	// wrote into the root summary through rewrites, byte for byte; see
@@ -651,3 +665,16 @@ type CodeLearning struct {
 	EndLine int    `json:"end_line,omitempty"` // End line for ranges (optional)
 	Finding string `json:"finding"`            // What was learned
 }
+
+// LinkedCommit is one trailer-less link from a checkpoint to a commit; see
+// WriteOptions.LinkedCommits. The server links it only after verifying the
+// commit, so Repo is a hint for finding which code repository holds SHA when
+// one checkpoint store serves several.
+type LinkedCommit struct {
+	// SHA is the full lowercase commit hash.
+	SHA string `json:"sha"`
+	// Repo is the code repository as <forge>/<owner>/<repo> (e.g.
+	// gh/entireio/cli), resolved from the git remote that holds the commit.
+	// Empty when it could not be resolved.
+	Repo string `json:"repo,omitempty"`
+}

cmd/entire/cli/agent_help_cmd.go

@@ -191,6 +191,14 @@ var agentHelpClassification = map[string]agentHelpFacts{
 // true for both audiences (e.g. "these endpoints are internal and can change")
 // belongs in Long instead, where both see it.
 var agentHelpGuidance = map[string]string{
+	"session attach": "Commits made during a session are linked to it automatically. Use this\n" +
+		"only when one was missed: `entire session attach <session-id> --commit <sha>`\n" +
+		"(default HEAD). Run it without --force first: it prints what it would do\n" +
+		"(rewrite unpushed commits to add the trailer, or record a link to a pushed\n" +
+		"commit and push the session transcript) and exits non-zero without changing\n" +
+		"anything. Show the user that output and ask them; pass --force only after\n" +
+		"they agree to that exact change, never pre-emptively. A link to a pushed\n" +
+		"commit counts only when its author attaches it.",
 	"api": "LAST RESORT. Right in two cases: you are developing against Entire's own\n" +
 		"APIs and want a raw response, or no first-class command covers your need.\n" +
 		"Otherwise prefer the command built for the job (checkpoint, session, trail,\n" +