fix(herdr): close Phase 4 item 2 — actually ask the agent for a handoff

Release already validated and uploaded a §6.1 handoff, but nothing ever
told the agent the .orchestra-handoff.json convention existed, so the
file it waited on never got written. rotate() now prompts the agent
once via a new optional herdr.HandoffRequester capability
(CLIAdapter.RequestHandoff) when the file is missing, and defers
Release until it appears, mirroring the .orchestra-report.md/B3 ask
pattern rather than inventing a handoff.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01W1rkJ2hBMybnJctPbcy4tT

internal/herdr/adapter.go

@@ -113,6 +113,28 @@ This worktree's anchor and TASK.md have already been verified by the plane befor
 func (a CLIAdapter) Bootstrap(ctx context.Context, s Session, ref string) error {
 	return a.Client.Prompt(ctx, s.PaneID, fmt.Sprintf(bootstrapPrompt, ref), time.Minute)
 }
+
+// handoffPrompt is Phase 4 item 2's missing half (AUDIT.md): Release already
+// validates and uploads a §6.1 handoff the agent wrote, but nothing ever told
+// the agent that convention exists. rotate() sends this once occupancy crosses
+// the hard threshold at a turn boundary, mirroring the .orchestra-report.md
+// convention B3 established for completion — the plane still never invents a
+// handoff, it only asks the agent to produce one, then validates it in Release.
+const handoffPrompt = `Orchestra is about to rotate this task to a fresh session (context budget reached).
+Before you stop, write a §6.1 handoff to ` + HandoffFile + ` at the worktree root, a JSON object with at least:
+{"meta":{"id":"<any stable string for this handoff>"},"anchor":{"git_sha":"<current HEAD via git rev-parse HEAD>","branch":"<current branch>","dirty":[{"path":"<repo-relative path>","sha256":"<sha256 of its current contents>"}, ...for any uncommitted files]},"knowledge":{...whatever structured context the next agent needs...}}
+Do not edit TASK.md. Do not fabricate the git_sha or dirty file hashes — read them for real. Once written, stop normally.`
+
+// RequestHandoff prompts the agent to write HandoffFile before Release reads
+// it. Optional capability: adapters without a live pane (tests, etc.) can
+// omit it and rotate() falls back to waiting on the file appearing on its own.
+type HandoffRequester interface {
+	RequestHandoff(context.Context, Session) error
+}
+
+func (a CLIAdapter) RequestHandoff(ctx context.Context, s Session) error {
+	return a.Client.Prompt(ctx, s.PaneID, handoffPrompt, time.Minute)
+}
 // Release reads the §6.1 handoff the agent wrote to HandoffFile at the
 // worktree root, validates its schema and anchor against the worktree's real
 // HEAD, uploads it to CAS, and only then releases herdr's claim on the pane

internal/herdr/herdr.go

@@ -153,6 +153,10 @@ type Session struct {
 	// session's lease was created — the immutable-spec hash continuity's
 	// pickup validation compares against on the next rotation (§6.2).
 	TaskFileSHA string `json:"task_file_sha,omitempty"`
+	// HandoffRequested is set once rotate() has prompted the agent to write
+	// its §6.1 handoff (HandoffFile) — avoids re-sending the same prompt
+	// every tick while Release keeps waiting for the file to appear.
+	HandoffRequested bool `json:"handoff_requested,omitempty"`
 }
 
 func (c *Client) Prompt(ctx context.Context, pane, text string, wait time.Duration) error {

internal/orchestrator/orchestrator.go

@@ -499,6 +499,20 @@ func (c *Coordinator) rotate(ctx context.Context, hard float64) {
 		} else {
 			c.recordTurnBoundaryDegraded()
 		}
+		if requester, ok := a.(herdr.HandoffRequester); ok {
+			if _, statErr := os.Stat(filepath.Join(session.Worktree, herdr.HandoffFile)); statErr != nil {
+				if !session.HandoffRequested {
+					if reqErr := requester.RequestHandoff(ctx, session); reqErr == nil {
+						session.HandoffRequested = true
+						c.mu.Lock()
+						c.sessions[taskID] = session
+						_ = c.saveSessionsLocked()
+						c.mu.Unlock()
+					}
+				}
+				continue
+			}
+		}
 		ref, err := a.Release(ctx, session)
 		if err != nil {
 			continue

internal/orchestrator/rotation_test.go

@@ -9,6 +9,7 @@ import (
 	"orchestra/internal/herdr"
 	"orchestra/internal/orchestrator"
 	"orchestra/internal/store"
+	"os"
 	"os/exec"
 	"testing"
 	"time"
@@ -396,3 +397,82 @@ func TestNoTurnBoundarySupportDegradesVisibly(t *testing.T) {
 		t.Fatal("missing Face B support was not recorded as degraded")
 	}
 }
+
+type handoffRequestingAdapter struct {
+	fakeAdapter
+	requests int
+}
+
+func (a *handoffRequestingAdapter) RequestHandoff(context.Context, herdr.Session) error {
+	a.requests++
+	return nil
+}
+
+// TestRotationRequestsHandoffBeforeReleasing guards Phase 4 item 2 (AUDIT.md):
+// rotate() must not call Release until the agent has been told to write its
+// §6.1 handoff and the file actually exists — never invent or skip the ask.
+func TestRotationRequestsHandoffBeforeReleasing(t *testing.T) {
+	repo := t.TempDir()
+	run(t, repo, "init")
+	run(t, repo, "config", "user.email", "t@t")
+	run(t, repo, "config", "user.name", "t")
+	run(t, repo, "commit", "--allow-empty", "-m", "init")
+
+	s, err := store.Open(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Append(domain.Event{ID: domain.NewID(), Type: "TaskCreated", TaskID: "t1", Surface: string(authz.System), Payload: mustJSON(map[string]any{
+		"source": "jsonl", "external_id": "1", "project": "p",
+	})}); err != nil {
+		t.Fatal(err)
+	}
+	task := s.Tasks()[0]
+	ref, err := s.PutArtifact([]byte("handoff"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	a := &handoffRequestingAdapter{fakeAdapter: fakeAdapter{occupancy: .95, boundary: true, ref: ref}}
+	c := &orchestrator.Coordinator{Store: s, Worktrees: worktrees{path: repo}, Adapters: adapters{a}, StatePath: t.TempDir() + "/sessions.json"}
+
+	leaseEvt, err := s.Lease(task.ID, "h1", time.Minute)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := c.Start(context.Background(), leaseEvt); err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go c.Monitor(ctx, .8, time.Millisecond)
+
+	deadline := time.Now().Add(200 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		time.Sleep(time.Millisecond)
+	}
+	if a.requests == 0 {
+		t.Fatal("rotate never asked the agent to write a handoff")
+	}
+	if a.releases != 0 {
+		t.Fatal("rotate called Release before the handoff file existed")
+	}
+	if got, ok := s.Task(task.ID); !ok || got.State != domain.StateLeased {
+		t.Fatalf("task rotated without a handoff file: state=%v ok=%v", got.State, ok)
+	}
+
+	if err := os.WriteFile(repo+"/"+herdr.HandoffFile, []byte("{}"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	deadline = time.Now().Add(time.Second)
+	for time.Now().Before(deadline) {
+		if got, ok := s.Task(task.ID); ok && got.State == domain.StateQueued {
+			break
+		}
+		time.Sleep(time.Millisecond)
+	}
+	if a.releases == 0 {
+		t.Fatal("rotate never called Release once the handoff file appeared")
+	}
+}