feat(attach): explicit-target review attach bound to a commit SHA

Adds an explicit-target mode to 'entire session attach --review':
--checkpoint-id <id> --commit-sha <sha> creates the checkpoint under a
caller-supplied ID bound to the given commit via a new commit_sha metadata
field, instead of resolving HEAD's Entire-Checkpoint trailer and amending
the commit.

This unblocks platform review provenance for commits that cannot carry a
trailer (merge commits, squash merges, human pushes): the reviewed commit
is immutable once pushed, so the trailer-based linkage requires a force
push that is never allowed. The platform mints the checkpoint ID and
passes the reviewed commit's SHA; the binding lives in checkpoint
metadata, not the commit message.

- commit_sha (omitempty) on Metadata, CheckpointSummary and WriteOptions,
  plumbed through the session and summary writers.
- Explicit-target mode skips trailer resolution, the session-has-checkpoint
  refusal (the reviewer's own eagerly-condensed checkpoint is irrelevant to
  the new checkpoint), and never amends HEAD.
- Retried attaches with the same target are idempotent no-op successes so
  the platform can safely retry the publication script.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: dipree

api/checkpoint/metadata.go

@@ -149,6 +149,12 @@ type WriteOptions struct {
 	// Kind identifies the session purpose (e.g., "agent_review"). Empty for normal sessions.
 	Kind string
 
+	// CommitSHA is the full SHA of the user-code commit this checkpoint is
+	// bound to, for checkpoints attached to a commit without an
+	// Entire-Checkpoint trailer (e.g. platform-published review provenance
+	// keyed by the reviewed commit). Empty for trailer-linked checkpoints.
+	CommitSHA string
+
 	// ReviewSkills is the snapshot of skills used (only meaningful when Kind is a review kind).
 	// May be empty when a review is attached post-hoc without declared skills.
 	ReviewSkills []string
@@ -393,6 +399,12 @@ type Metadata struct {
 	// Kind identifies the session purpose (e.g., "agent_review"). Empty for normal sessions.
 	Kind string `json:"kind,omitempty"`
 
+	// CommitSHA is the full SHA of the user-code commit this checkpoint is
+	// bound to, for checkpoints attached without an Entire-Checkpoint
+	// trailer (e.g. platform-published review provenance). Empty for
+	// trailer-linked checkpoints.
+	CommitSHA string `json:"commit_sha,omitempty"`
+
 	// ReviewSkills lists the review skills that were run (only set when Kind is a review kind).
 	// May be empty when a review was attached post-hoc without declared skills.
 	ReviewSkills []string `json:"review_skills,omitempty"`
@@ -503,6 +515,12 @@ type CheckpointSummary struct {
 	// agent history (a session with Kind == "imported"): read-only and
 	// commit-less.
 	Imported bool `json:"imported,omitempty"`
+
+	// CommitSHA is the full SHA of the user-code commit this checkpoint is
+	// bound to, for checkpoints attached without an Entire-Checkpoint
+	// trailer (e.g. platform-published review provenance). Empty for
+	// trailer-linked checkpoints.
+	CommitSHA string `json:"commit_sha,omitempty"`
 }
 
 // SessionMetrics contains hook-provided session metrics from agents that report

cmd/entire/cli/attach.go

@@ -8,6 +8,7 @@ import (
 	"log/slog"
 	"os"
 	"os/exec"
+	"regexp"
 	"strings"
 	"time"
 
@@ -35,6 +36,9 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// fullCommitSHARegex matches a full 40-hex git commit SHA (lowercased input).
+var fullCommitSHARegex = regexp.MustCompile(`^[0-9a-f]{40}$`)
+
 // attachOptions carries optional flags for runAttach. Force is the original
 // flag; Review opts the attach into recording the session as an
 // agent_review in the checkpoint metadata.
@@ -54,6 +58,22 @@ type attachOptions struct {
 	// transcript's first user prompt. Set from a pending-review marker when
 	// `entire attach --review` adopts the prompt the user was asked to run.
 	ReviewPromptOverride string
+	// CheckpointID, when non-empty, is the explicit target checkpoint ID to
+	// create instead of resolving one from HEAD's Entire-Checkpoint trailer.
+	// Used by platform review-provenance publication, where the server mints
+	// the ID. Requires Review and CommitSHA; the explicit-target mode never
+	// amends HEAD (the binding is the recorded CommitSHA, not a trailer).
+	CheckpointID id.CheckpointID
+	// CommitSHA, when non-empty, is the full SHA of the user-code commit this
+	// attach is bound to. Recorded in the checkpoint metadata (commit_sha) in
+	// place of a commit-message trailer. Requires Review and CheckpointID.
+	CommitSHA string
+}
+
+// explicitTarget reports whether this attach targets a caller-supplied
+// checkpoint ID bound to a commit SHA (no trailer resolution, no HEAD amend).
+func (opts attachOptions) explicitTarget() bool {
+	return !opts.CheckpointID.IsEmpty()
 }
 
 // committedRefs resolves the committed metadata topology.
@@ -73,10 +93,12 @@ func openAttachStore(ctx context.Context, repo *git.Repository, refs cpkg.Persis
 
 func newAttachCmd() *cobra.Command {
 	var (
-		force      bool
-		agentFlag  string
-		reviewFlag bool
-		skillsFlag []string
+		force            bool
+		agentFlag        string
+		reviewFlag       bool
+		skillsFlag       []string
+		checkpointIDFlag string
+		commitSHAFlag    string
 	)
 	cmd := &cobra.Command{
 		Use:   "attach <session-id>",
@@ -115,6 +137,27 @@ the transcript and prints the detected agent name.`,
 				Review:               reviewFlag,
 				ReviewSkillsOverride: skillsFlag,
 			}
+			// Explicit-target mode: a server-minted checkpoint ID bound to a
+			// commit SHA, with no trailer resolution and no HEAD amend. Both
+			// flags travel together and only make sense for reviews.
+			if checkpointIDFlag != "" || commitSHAFlag != "" {
+				if checkpointIDFlag == "" || commitSHAFlag == "" {
+					return errors.New("--checkpoint-id and --commit-sha must be used together")
+				}
+				if !reviewFlag {
+					return errors.New("--checkpoint-id/--commit-sha require --review")
+				}
+				cpID, idErr := id.NewCheckpointID(checkpointIDFlag)
+				if idErr != nil {
+					return fmt.Errorf("invalid --checkpoint-id: %w", idErr)
+				}
+				normalizedSHA := strings.ToLower(commitSHAFlag)
+				if !fullCommitSHARegex.MatchString(normalizedSHA) {
+					return fmt.Errorf("invalid --commit-sha (want full 40-hex SHA): %s", commitSHAFlag)
+				}
+				opts.CheckpointID = cpID
+				opts.CommitSHA = normalizedSHA
+			}
 			// When tagging as a review, consume any pending-review marker left
 			// by `entire review` for an agent it could not launch itself: adopt
 			// its agent / skills / prompt so the manual attach matches what the
@@ -149,6 +192,8 @@ the transcript and prints the detected agent name.`,
 	cmd.Flags().StringVarP(&agentFlag, "agent", "a", string(agent.DefaultAgentName), "Agent that created the session (see 'entire agent list' for registered agents, including external)")
 	cmd.Flags().BoolVar(&reviewFlag, "review", false, "Tag the attached session as an agent review")
 	cmd.Flags().StringSliceVar(&skillsFlag, "skills", nil, "Optional: declare which review skills were run in this session. Only used with --review")
+	cmd.Flags().StringVar(&checkpointIDFlag, "checkpoint-id", "", "Explicit checkpoint ID to create for this attach (requires --review and --commit-sha; skips trailer resolution and never amends HEAD)")
+	cmd.Flags().StringVar(&commitSHAFlag, "commit-sha", "", "Full SHA of the commit this attach is bound to, recorded as commit_sha in the checkpoint metadata (requires --review and --checkpoint-id)")
 	return cmd
 }
 
@@ -237,7 +282,10 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 	}
 
 	// If session already has a checkpoint, just offer to link it.
-	if existingState != nil && !existingState.LastCheckpointID.IsEmpty() {
+	// Explicit-target mode is exempt: it authors a separate new checkpoint
+	// under the caller-supplied ID, so the session's own checkpoint (e.g.
+	// from the session-stop hook's eager condense) is irrelevant.
+	if existingState != nil && !existingState.LastCheckpointID.IsEmpty() && !opts.explicitTarget() {
 		// Review-upgrade isn't supported yet: the existing checkpoint's
 		// metadata tree would need to be rewritten with Kind/ReviewSkills/
 		// ReviewPrompt set, and a new commit pushed onto entire/checkpoints/v1.
@@ -288,8 +336,16 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 	meta := extractTranscriptMetadata(transcriptData)
 	warnEmptyTranscriptMetadata(errW, ag.Name(), meta, opts)
 
-	// Determine checkpoint ID: reuse from HEAD if one exists, otherwise generate new.
-	checkpointID, isExistingCheckpoint := resolveCheckpointID(ctx, headCommit)
+	// Determine checkpoint ID: an explicit target uses the caller-supplied ID
+	// (new by construction, bound to opts.CommitSHA); otherwise reuse HEAD's
+	// trailer if present or generate a fresh ID.
+	var checkpointID id.CheckpointID
+	var isExistingCheckpoint bool
+	if opts.explicitTarget() {
+		checkpointID, isExistingCheckpoint = opts.CheckpointID, false
+	} else {
+		checkpointID, isExistingCheckpoint = resolveCheckpointID(ctx, headCommit)
+	}
 
 	// If HEAD references an existing checkpoint, make sure we have it locally
 	// before writing — otherwise we'd create a fresh session 0 under the same
@@ -335,6 +391,20 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 		}
 	}
 
+	// Explicit-target idempotency: a retried attach with the same server-minted
+	// checkpoint ID and session is a no-op success, not an error — the caller
+	// (platform provenance publication) retries the whole script.
+	if opts.explicitTarget() {
+		exists, readErr := checkpointHasSessionMetadata(ctx, repo, refs, checkpointID, sessionID)
+		if readErr != nil {
+			return fmt.Errorf("failed to check checkpoint %s for session %s: %w", checkpointID.String(), sessionID, readErr)
+		}
+		if exists {
+			fmt.Fprintf(w, "Session %s already attached to checkpoint %s\n", sessionID, checkpointID.String())
+			return nil
+		}
+	}
+
 	author, err := GetGitAuthor(ctx)
 	if err != nil {
 		return fmt.Errorf("failed to get git author: %w", err)
@@ -368,6 +438,9 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 		writeOpts.ReviewPrompt = reviewPromptForAttach(meta, opts)
 		writeOpts.HasReview = true
 	}
+	if opts.explicitTarget() {
+		writeOpts.CommitSHA = opts.CommitSHA
+	}
 
 	if err := store.Write(ctx, cpkg.Session(writeOpts)); err != nil {
 		return fmt.Errorf("failed to write checkpoint: %w", err)
@@ -386,6 +459,12 @@ func runAttach(ctx context.Context, w, errW io.Writer, sessionID string, agentNa
 	}
 
 	fmt.Fprintf(w, "  Created checkpoint %s\n", checkpointID)
+	// Explicit-target attaches are bound to their commit via the recorded
+	// commit_sha, not a commit-message trailer — never amend HEAD.
+	if opts.explicitTarget() {
+		fmt.Fprintf(w, "  Bound to commit %s\n", opts.CommitSHA)
+		return nil
+	}
 	amendOrPrintTrailer(logCtx, w, errW, headCommit, checkpointID.String(), opts.Force)
 
 	return nil

cmd/entire/cli/attach_test.go

@@ -1165,6 +1165,167 @@ func TestAttach_ReviewWithExistingCheckpointErrors(t *testing.T) {
 	}
 }
 
+// Explicit-target mode: the platform review-provenance flow supplies a
+// server-minted checkpoint ID and the reviewed commit's SHA. The attach must
+// create that checkpoint bound to the commit via metadata (commit_sha), even
+// when HEAD carries no Entire-Checkpoint trailer, and must never amend HEAD.
+func TestAttach_ReviewExplicitTargetCreatesShaBoundCheckpoint(t *testing.T) {
+	setupAttachTestRepo(t)
+
+	repoRoot := mustGetwd(t)
+	repo, err := git.PlainOpen(repoRoot)
+	if err != nil {
+		t.Fatal(err)
+	}
+	headRef, err := repo.Head()
+	if err != nil {
+		t.Fatal(err)
+	}
+	headSHA := headRef.Hash().String()
+	headCommit, err := repo.CommitObject(headRef.Hash())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(trailers.ParseAllCheckpoints(headCommit.Message)) != 0 {
+		t.Fatal("test requires a HEAD without an Entire-Checkpoint trailer")
+	}
+	originalMessage := headCommit.Message
+
+	sessionID := "review-session-explicit-target"
+	setupClaudeTranscript(t, sessionID, `{"type":"user","message":{"role":"user","content":"please review"},"uuid":"u1"}
+`)
+	// Simulate the session-stop hook's eager condense: the reviewer session
+	// already holds its own checkpoint. Explicit-target mode must not refuse.
+	ownCheckpointID, err := cpkg.GenerateCheckpointID(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	stateStore, err := session.NewStateStore(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := stateStore.Save(context.Background(), &session.State{
+		SessionID:        sessionID,
+		StartedAt:        time.Now(),
+		WorktreePath:     repoRoot,
+		AgentType:        agent.AgentTypeClaudeCode,
+		LastCheckpointID: ownCheckpointID,
+	}); err != nil {
+		t.Fatalf("seed session state: %v", err)
+	}
+
+	targetID := id.CheckpointID("aabbccddeeff")
+	opts := attachOptions{
+		Force:                true,
+		Review:               true,
+		ReviewSkillsOverride: []string{"/review"},
+		CheckpointID:         targetID,
+		CommitSHA:            headSHA,
+	}
+	var out bytes.Buffer
+	if err := runAttach(context.Background(), &out, &out, sessionID, agent.AgentNameClaudeCode, opts); err != nil {
+		t.Fatalf("explicit-target review attach failed: %v", err)
+	}
+
+	// Checkpoint exists at the supplied ID with the commit binding recorded.
+	store := cpkg.NewGitStore(repo, cpkg.DefaultV1Refs())
+	summary, err := store.Read(context.Background(), targetID)
+	if err != nil {
+		t.Fatalf("Read(%s): %v", targetID, err)
+	}
+	if summary == nil {
+		t.Fatalf("checkpoint %s not created", targetID)
+	}
+	if summary.CommitSHA != headSHA {
+		t.Errorf("summary.CommitSHA = %q, want %q", summary.CommitSHA, headSHA)
+	}
+	if !summary.HasReview {
+		t.Error("summary.HasReview should be true")
+	}
+	if len(summary.Sessions) != 1 {
+		t.Fatalf("checkpoint has %d sessions, want 1", len(summary.Sessions))
+	}
+	metadata, err := store.ReadSessionMetadata(context.Background(), targetID, 0)
+	if err != nil {
+		t.Fatalf("ReadSessionMetadata: %v", err)
+	}
+	if metadata.SessionID != sessionID {
+		t.Errorf("session metadata SessionID = %q, want %q", metadata.SessionID, sessionID)
+	}
+	if metadata.CommitSHA != headSHA {
+		t.Errorf("session metadata CommitSHA = %q, want %q", metadata.CommitSHA, headSHA)
+	}
+	if metadata.Kind != string(session.KindAgentReview) {
+		t.Errorf("session metadata Kind = %q, want agent_review", metadata.Kind)
+	}
+
+	// HEAD must be untouched: same commit, no trailer appended.
+	newHeadRef, err := repo.Head()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if newHeadRef.Hash().String() != headSHA {
+		t.Errorf("HEAD moved from %s to %s; explicit-target attach must not amend", headSHA, newHeadRef.Hash())
+	}
+	newHeadCommit, err := repo.CommitObject(newHeadRef.Hash())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if newHeadCommit.Message != originalMessage {
+		t.Error("HEAD commit message changed; explicit-target attach must not amend")
+	}
+
+	// Retried attach with the same target is an idempotent no-op success.
+	out.Reset()
+	if err := runAttach(context.Background(), &out, &out, sessionID, agent.AgentNameClaudeCode, opts); err != nil {
+		t.Fatalf("retried explicit-target attach should be a no-op success: %v", err)
+	}
+	if !strings.Contains(out.String(), "already attached") {
+		t.Errorf("expected idempotent no-op message, got: %q", out.String())
+	}
+	summary, err = store.Read(context.Background(), targetID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(summary.Sessions) != 1 {
+		t.Errorf("retry duplicated the session: %d sessions, want 1", len(summary.Sessions))
+	}
+}
+
+// The explicit-target flags are a unit: both must be supplied, only with
+// --review, and the commit SHA must be a full 40-hex value.
+func TestAttach_ExplicitTargetFlagValidation(t *testing.T) {
+	setupAttachTestRepo(t)
+
+	run := func(args ...string) error {
+		cmd := newAttachCmd()
+		var out bytes.Buffer
+		cmd.SetOut(&out)
+		cmd.SetErr(&out)
+		cmd.SetArgs(args)
+		return cmd.Execute()
+	}
+
+	fullSHA := strings.Repeat("ab", 20)
+	cases := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{"checkpoint-id without commit-sha", []string{"s1", "--review", "--checkpoint-id", "aabbccddeeff"}, "must be used together"},
+		{"commit-sha without checkpoint-id", []string{"s1", "--review", "--commit-sha", fullSHA}, "must be used together"},
+		{"without review", []string{"s1", "--checkpoint-id", "aabbccddeeff", "--commit-sha", fullSHA}, "require --review"},
+		{"bad checkpoint id", []string{"s1", "--review", "--checkpoint-id", "not/valid", "--commit-sha", fullSHA}, "invalid --checkpoint-id"},
+		{"short commit sha", []string{"s1", "--review", "--checkpoint-id", "aabbccddeeff", "--commit-sha", "abc123"}, "invalid --commit-sha"},
+	}
+	for _, tc := range cases {
+		err := run(tc.args...)
+		if err == nil || !strings.Contains(err.Error(), tc.want) {
+			t.Errorf("%s: got %v, want error containing %q", tc.name, err, tc.want)
+		}
+	}
+}
+
 // Regression for the second "review-attach overwrote the session on the
 // checkpoint" report: a DIFFERENT session ID (not present in the existing
 // checkpoint) must APPEND at the next-available index, not overwrite