relay-flow 0.2.11-alpha → 0.3.1-alpha

package/internal/execution/temporal/activities.go

@@ -162,7 +162,8 @@ func (a *Activities) LoadNodeRuntime(ctx context.Context, id run.ID, node string
 
 // EnsureNodeRuntime uses only persisted terminal/session IDs on the normal
 // path. A live terminal is rebound to the new visit; otherwise EnsureTerminal
-// creates a replacement and its direct ID is persisted immediately.
+// creates a replacement and its direct ID is persisted immediately. A stored
+// session receives feedback whether its terminal is reused or replaced.
 func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, repoPath string, spec harness.LaunchSpec, rt NodeRuntime) (NodeRuntime, error) {
 	a.runtimeMu.Lock()
 	defer a.runtimeMu.Unlock()
@@ -204,6 +205,10 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 	rt.TerminalID = currentRuntime.TerminalID
 	rt.SessionID = currentRuntime.SessionID
 	spec.ResumeID = rt.SessionID
+	promptKind := harness.PromptInitial
+	if rt.SessionID != "" {
+		promptKind = harness.PromptFeedback
+	}
 	stored := runner.Terminal{ID: rt.TerminalID, Title: spec.Title}
 	terminal, live, err := a.Runner.FindTerminal(ctx, stored)
 	if err != nil {
@@ -218,7 +223,7 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 			// Same-visit retry/restart is silent: do not render, build, or send.
 			return rt, nil
 		}
-		prompt, err := a.Harness.RenderPrompt(harness.PromptFeedback, spec.PromptData, spec.NudgePrompt)
+		prompt, err := a.Harness.RenderPrompt(promptKind, spec.PromptData, spec.NudgePrompt)
 		if err != nil {
 			return NodeRuntime{}, err
 		}
@@ -232,14 +237,14 @@ func (a *Activities) EnsureNodeRuntime(ctx context.Context, nw run.NodeWork, rep
 		}
 	}
 
-	// An initial or replacement terminal resumes the stored session and
-	// receives the rendered initial prompt. Same-visit replacements omit the
-	// node nudge; a new visit includes it.
+	// A fresh session receives the initial prompt; a stored session receives
+	// feedback even when its terminal must be replaced. Same-visit
+	// replacements omit the node nudge; a new visit includes it.
 	nudge := ""
 	if rt.NodeVisitID == "" || revisit {
 		nudge = spec.NudgePrompt
 	}
-	spec.Prompt, err = a.Harness.RenderPrompt(harness.PromptInitial, spec.PromptData, nudge)
+	spec.Prompt, err = a.Harness.RenderPrompt(promptKind, spec.PromptData, nudge)
 	if err != nil {
 		return NodeRuntime{}, err
 	}

package/internal/execution/temporal/end_cleanup_order_test.go

@@ -0,0 +1,147 @@
+package temporal
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+	"go.temporal.io/sdk/testsuite"
+	temporalworkflow "go.temporal.io/sdk/workflow"
+)
+
+// The workflow uses a start-to-end graph so the test isolates end cleanup;
+// terminalLive models the persisted node terminal that finalization would close.
+type endCleanupActivities struct {
+	events                      []string
+	cleanupDirty                bool
+	terminalLive                bool
+	completionObserved          bool
+	completionObservedOnFailure bool
+}
+
+func (a *endCleanupActivities) EnsureMailboxes(context.Context, run.Work, []task.MailboxSpec) (map[string]task.Mailbox, error) {
+	return map[string]task.Mailbox{}, nil
+}
+
+func (a *endCleanupActivities) ValidateAgents(context.Context, string, []string) error {
+	return nil
+}
+
+func (a *endCleanupActivities) ProjectionUpsertStep(context.Context, run.StepEntry) error {
+	return nil
+}
+
+func (a *endCleanupActivities) ApplyTaskConfig(context.Context, run.Work, string, *task.Mailbox, map[string]any) error {
+	return nil
+}
+
+func (a *endCleanupActivities) EnsureEnvironment(context.Context, run.Work, string) (runner.Environment, error) {
+	return runner.Environment{}, nil
+}
+
+func (a *endCleanupActivities) SetEnvironmentStatus(context.Context, run.Work, string, string) error {
+	return nil
+}
+
+func (a *endCleanupActivities) CleanupRun(context.Context, run.Work, string) error {
+	if a.cleanupDirty {
+		a.cleanupDirty = false
+		a.completionObservedOnFailure = a.completionObserved
+		if a.terminalLive {
+			a.events = append(a.events, "cleanup-failed-terminal-live")
+		} else {
+			a.events = append(a.events, "cleanup-failed-terminal-closed")
+		}
+		return errors.New("ticket checkout is dirty; commit required before runner cleanup")
+	}
+	a.events = append(a.events, "cleanup")
+	return nil
+}
+
+func (a *endCleanupActivities) FinalizeNodeRuntimes(context.Context, run.Work, string, run.RuntimePolicy) error {
+	if a.terminalLive {
+		a.terminalLive = false
+		a.events = append(a.events, "finalize-terminal-closed")
+	} else {
+		a.events = append(a.events, "finalize-terminal-already-closed")
+	}
+	return nil
+}
+
+func (a *endCleanupActivities) ProjectionUpdateRetry(context.Context, run.ID, *run.RetryStatus) error {
+	return nil
+}
+
+func (a *endCleanupActivities) ProjectionUpdateState(_ context.Context, _ run.ID, state run.State, _ string, _ *time.Time) error {
+	if state == run.StateCompleted {
+		a.completionObserved = true
+		if a.terminalLive {
+			a.events = append(a.events, "completed-terminal-live")
+		} else {
+			a.events = append(a.events, "completed")
+		}
+	}
+	return nil
+}
+
+func endCleanupOrderingWorkflow(ctx temporalworkflow.Context, start run.Start) error {
+	state := newWorkflowState(ctx, start)
+	reason := "canceled"
+	return runGraph(ctx, start, state, temporalworkflow.GetSignalChannel(ctx, cancelReasonSignalName), &reason)
+}
+
+func TestTemporalEndCleanupRunsBeforeRuntimeFinalization(t *testing.T) {
+	for _, cleanup := range []bool{true, false} {
+		t.Run(map[bool]string{true: "enabled", false: "disabled"}[cleanup], func(t *testing.T) {
+			activities := &endCleanupActivities{cleanupDirty: cleanup, terminalLive: true}
+			var suite testsuite.WorkflowTestSuite
+			env := suite.NewTestWorkflowEnvironment()
+			env.RegisterWorkflow(endCleanupOrderingWorkflow)
+			env.RegisterActivity(activities)
+			start := run.Start{
+				ID: "repo/cleanup/T-1", Repo: "repo", RepoPath: t.TempDir(),
+				Workflow: workflow.Workflow{
+					Name: "cleanup", CleanupRunnerOnEnd: cleanup,
+					Nodes: map[string]workflow.Node{
+						"start": {OnSuccess: []workflow.Route{{Target: "end"}}},
+						"end":   {},
+					},
+				},
+				Ticket: task.TicketRef{ID: "T-1", Key: "T-1"},
+			}
+			env.ExecuteWorkflow(endCleanupOrderingWorkflow, start)
+			if err := env.GetWorkflowError(); err != nil {
+				t.Fatalf("workflow error: %v", err)
+			}
+			if cleanup {
+				if activities.completionObservedOnFailure {
+					t.Fatal("run was marked completed while dirty cleanup was retrying")
+				}
+				want := []string{"cleanup-failed-terminal-live", "cleanup", "finalize-terminal-closed", "completed"}
+				if len(activities.events) != len(want) {
+					t.Fatalf("activity order = %v, want %v", activities.events, want)
+				}
+				for i := range want {
+					if activities.events[i] != want[i] {
+						t.Fatalf("activity order = %v, want %v", activities.events, want)
+					}
+				}
+			} else {
+				want := []string{"finalize-terminal-closed", "completed"}
+				if len(activities.events) != len(want) {
+					t.Fatalf("cleanup-disabled activity order = %v, want %v", activities.events, want)
+				}
+				for i := range want {
+					if activities.events[i] != want[i] {
+						t.Fatalf("cleanup-disabled activity order = %v, want %v", activities.events, want)
+					}
+				}
+			}
+		})
+	}
+}

package/internal/execution/temporal/interpreter.go

@@ -597,6 +597,17 @@ func runGraph(ctx temporalworkflow.Context, start run.Start, state *workflowStat
 	if wf.CleanupRunnerOnEnd {
 		finalPolicy.KeepTerminalsAlive = false
 	}
+	// Cleanup must run before finalizing node runtimes when enabled. The
+	// runner performs its Git cleanliness check before closing terminals, so a
+	// dirty checkout leaves the agent terminal available for a commit while
+	// retryActivity waits.
+	if wf.CleanupRunnerOnEnd {
+		if _, err := retryActivity(ctx, state, work, "", func() (struct{}, error) {
+			return executeActivity[struct{}](ctx, activityCleanupRun, work, start.RepoPath)
+		}); err != nil {
+			return err
+		}
+	}
 	if _, err := retryActivity(ctx, state, work, "", func() (struct{}, error) {
 		return executeActivity[struct{}](ctx, activityFinalizeNodeRuntimes, work, start.RepoPath, finalPolicy)
 	}); err != nil {
@@ -605,13 +616,6 @@ func runGraph(ctx temporalworkflow.Context, start run.Start, state *workflowStat
 	for node := range state.bindings {
 		applyRuntimePolicy(state, node, finalPolicy)
 	}
-	if wf.CleanupRunnerOnEnd {
-		if _, err := retryActivity(ctx, state, work, "", func() (struct{}, error) {
-			return executeActivity[struct{}](ctx, activityCleanupRun, work, start.RepoPath)
-		}); err != nil {
-			return err
-		}
-	}
 	now := temporalworkflow.Now(ctx).UTC()
 	endStep.Status, endStep.FinishedAt = run.StepSucceeded, &now
 	if _, err := retryActivity(ctx, state, work, "end", func() (struct{}, error) {

package/internal/harness/opencode/opencode.go

@@ -88,7 +88,7 @@ func init() {
 type Harness struct {
 	templates Config
 	// listAgents is the test seam; nil → real `opencode agent list`.
-	listAgents func(ctx context.Context) ([]string, error)
+	listAgents func(ctx context.Context, repoPath string) ([]string, error)
 }
 
 // New returns the production Harness.
@@ -110,7 +110,7 @@ func (h *Harness) SetupRepo(_ context.Context, repoPath string) error {
 // ValidateAgent reports whether name is a known OpenCode agent for the
 // repo, per `opencode agent list` (agent names are the unindented first
 // tokens).
-func (h *Harness) ValidateAgent(ctx context.Context, _ string, agent string) error {
+func (h *Harness) ValidateAgent(ctx context.Context, repoPath, agent string) error {
 	if agent == "" {
 		return fmt.Errorf("opencode: agent name is empty")
 	}
@@ -118,7 +118,7 @@ func (h *Harness) ValidateAgent(ctx context.Context, _ string, agent string) err
 	if list == nil {
 		list = listAgents
 	}
-	names, err := list(ctx)
+	names, err := list(ctx, repoPath)
 	if err != nil {
 		return err
 	}
@@ -236,8 +236,10 @@ func relayFlowHome() (string, error) {
 
 // listAgents runs `opencode agent list` and returns the agent names
 // (the unindented lines' first tokens).
-func listAgents(ctx context.Context) ([]string, error) {
-	out, err := exec.CommandContext(ctx, "opencode", "agent", "list").Output()
+func listAgents(ctx context.Context, repoPath string) ([]string, error) {
+	cmd := exec.CommandContext(ctx, "opencode", "agent", "list")
+	cmd.Dir = repoPath
+	out, err := cmd.Output()
 	if err != nil {
 		return nil, fmt.Errorf("opencode agent list: %w", err)
 	}

package/internal/harness/opencode/opencode_test.go

@@ -14,7 +14,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const configuredPlugin = "relay-flow-plugin@0.2.11-alpha"
+const configuredPlugin = "relay-flow-plugin@0.3.1-alpha"
 
 func TestBuildCommandArgv(t *testing.T) {
 	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")

package/internal/harness/opencode/repo_setup.go

@@ -10,7 +10,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/config"
 )
 
-const relayFlowPlugin = "relay-flow-plugin@0.2.11-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.3.1-alpha"
 
 type jsoncToken struct {
 	kind       byte

package/internal/harness/opencode/validation_test.go

@@ -0,0 +1,106 @@
+package opencode
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestValidateAgentPassesRepositoryToListAgentsSeam(t *testing.T) {
+	repoPath := t.TempDir()
+	var gotRepoPath string
+	h := New()
+	h.listAgents = func(_ context.Context, path string) ([]string, error) {
+		gotRepoPath = path
+		return []string{"build"}, nil
+	}
+
+	if err := h.ValidateAgent(context.Background(), repoPath, "build"); err != nil {
+		t.Fatalf("ValidateAgent: %v", err)
+	}
+	if gotRepoPath != repoPath {
+		t.Fatalf("listAgents repoPath = %q, want %q", gotRepoPath, repoPath)
+	}
+}
+
+func TestValidateAgentUsesRepositoryWorkingDirectory(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("fake opencode uses a POSIX shell")
+	}
+
+	repoA := t.TempDir()
+	repoB := t.TempDir()
+	fakeDir := t.TempDir()
+	fake := filepath.Join(fakeDir, "opencode")
+	script := `#!/bin/sh
+set -eu
+[ "$#" -eq 2 ] && [ "$1" = "agent" ] && [ "$2" = "list" ] || exit 2
+actual=$(pwd)
+case "$actual" in
+  "$OPENCODE_REPO_A")
+    printf 'repo-a-agent details\n'
+    ;;
+  "$OPENCODE_REPO_B")
+    printf 'repo-b-agent details\n'
+    ;;
+  *)
+    printf 'unexpected working directory: %s\n' "$actual" >&2
+    exit 3
+    ;;
+esac
+printf '  ignored-indented\n'
+printf '[ignored-json]\n'
+printf '{"ignored":true}\n'
+`
+	if err := os.WriteFile(fake, []byte(script), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", fakeDir)
+	t.Setenv("OPENCODE_REPO_A", repoA)
+	t.Setenv("OPENCODE_REPO_B", repoB)
+
+	h := New()
+	if err := h.ValidateAgent(context.Background(), repoA, "repo-a-agent"); err != nil {
+		t.Fatalf("agent from repository A rejected: %v", err)
+	}
+	if err := h.ValidateAgent(context.Background(), repoB, "repo-b-agent"); err != nil {
+		t.Fatalf("agent from repository B rejected: %v", err)
+	}
+	if err := h.ValidateAgent(context.Background(), repoA, "repo-b-agent"); err == nil {
+		t.Fatal("repository B agent accepted while validating repository A")
+	}
+	if err := h.ValidateAgent(context.Background(), repoB, "repo-a-agent"); err == nil {
+		t.Fatal("repository A agent accepted while validating repository B")
+	}
+}
+
+func TestValidateAgentPropagatesListCommandFailure(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("fake opencode uses a POSIX shell")
+	}
+
+	fakeDir := t.TempDir()
+	fake := filepath.Join(fakeDir, "opencode")
+	script := `#!/bin/sh
+set -eu
+[ "$#" -eq 2 ] && [ "$1" = "agent" ] && [ "$2" = "list" ] || exit 2
+printf 'agent list failed\n' >&2
+exit 17
+`
+	if err := os.WriteFile(fake, []byte(script), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", fakeDir)
+
+	h := New()
+	err := h.ValidateAgent(context.Background(), t.TempDir(), "build")
+	if err == nil {
+		t.Fatal("ValidateAgent succeeded after opencode agent list failed")
+	}
+	if !strings.Contains(err.Error(), "opencode agent list") {
+		t.Fatalf("error = %q, want opencode agent list context", err)
+	}
+}

package/internal/harness/pi/pi.go

@@ -148,10 +148,11 @@ func (*Harness) FindSession(context.Context, string, string) (harness.Session, b
 }
 
 // RenderPrompt renders the selected initial or feedback template and the
-// node's nudge template. Named Pi agents are native prompt-template commands,
-// so the complete rendered text is supplied as the command arguments. HITL
-// approval is not encoded in the prompt; the Pi extension asks for approval
-// through ctx.ui.select.
+// node's nudge template. Initial prompts use Pi's native prompt-template
+// command syntax; feedback is sent to an existing session and must remain
+// raw so Pi does not expand the full prompt template again. HITL approval is
+// not encoded in the prompt; the Pi extension asks for approval through
+// ctx.ui.select.
 func (h *Harness) RenderPrompt(kind harness.PromptKind, data harness.PromptData, nudgeTemplate string) (string, error) {
 	var tmpl string
 	switch kind {
@@ -168,15 +169,20 @@ func (h *Harness) RenderPrompt(kind harness.PromptKind, data harness.PromptData,
 		}
 	}
 	prompt := appendPrompt(renderTemplate(tmpl, data), renderTemplate(nudgeTemplate, data))
-	return applyPromptTemplate(data.Agent, prompt), nil
+	if kind == harness.PromptInitial {
+		return applyPromptTemplate(data.Agent, prompt), nil
+	}
+	return prompt, nil
 }
 
 // BuildCommand returns the interactive Pi invocation. The runner supplies a
 // PTY for Pi's stdin/stdout; the rendered prompt is the final positional argv
 // value. A named workflow agent adds Pi's --prompt-template option for the
 // project-owned .pi/prompts/<agent>.md file and invokes it with its native
-// slash-command syntax. Pi 0.84.1 rejects a bare -- terminator, so none is
-// included. A non-empty ResumeID selects Pi's exact session-id resume option.
+// slash-command syntax only for a fresh launch. Resumed sessions receive the
+// raw feedback prompt so Pi does not expand the template a second time. Pi
+// 0.84.1 rejects a bare -- terminator, so none is included. A non-empty
+// ResumeID selects Pi's exact session-id resume option.
 func (*Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 	if err := validateAgentName(spec.Agent); err != nil {
 		return runner.Command{}, err
@@ -215,7 +221,11 @@ func (*Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
 	if spec.ResumeID != "" {
 		args = append(args, "--session-id", spec.ResumeID)
 	}
-	args = append(args, applyPromptTemplate(spec.Agent, spec.Prompt))
+	prompt := spec.Prompt
+	if spec.ResumeID == "" {
+		prompt = applyPromptTemplate(spec.Agent, prompt)
+	}
+	args = append(args, prompt)
 	return runner.Command{
 		Executable: "pi",
 		Args:       args,

package/internal/harness/pi/pi_test.go

@@ -148,7 +148,7 @@ func TestBuildCommandUsesNativePromptTemplate(t *testing.T) {
 	if err != nil {
 		t.Fatalf("BuildCommand(resume): %v", err)
 	}
-	want = []string{"--name", spec.Title, "--prompt-template", ".pi/prompts/coder.md", "--session-id", spec.ResumeID, "/coder " + spec.Prompt}
+	want = []string{"--name", spec.Title, "--prompt-template", ".pi/prompts/coder.md", "--session-id", spec.ResumeID, spec.Prompt}
 	if !reflect.DeepEqual(cmd.Args, want) {
 		t.Fatalf("resume Args = %#v, want %#v", cmd.Args, want)
 	}

package/internal/harness/pi/prompt_test.go

@@ -97,7 +97,7 @@ func TestPiPromptRetainsDefaultAgentLabel(t *testing.T) {
 	}
 }
 
-func TestPiRenderPromptUsesNativeTemplateCommandForNamedAgent(t *testing.T) {
+func TestPiRenderPromptUsesNativeTemplateCommandForInitialNamedAgent(t *testing.T) {
 	h := newPiHarness(t)
 	data := harness.PromptData{
 		TaskSystem: "jira",
@@ -120,7 +120,7 @@ func TestPiRenderPromptUsesNativeTemplateCommandForNamedAgent(t *testing.T) {
 	if err != nil {
 		t.Fatalf("RenderPrompt(feedback): %v", err)
 	}
-	wantFeedback := "/coder New feedback was added to the comments section of your mailbox subtask PAY-234. Read it.\n\nfeedback nudge"
+	wantFeedback := "New feedback was added to the comments section of your mailbox subtask PAY-234. Read it.\n\nfeedback nudge"
 	if feedback != wantFeedback {
 		t.Fatalf("feedback prompt = %q, want %q", feedback, wantFeedback)
 	}

package/internal/runner/clean.go

@@ -0,0 +1,38 @@
+package runner
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+// CheckCleanCheckout verifies the ticket-scoped checkout before runner cleanup.
+// A checkout that has already disappeared is an idempotent cleanup success;
+// callers preserve their existing roll-forward behavior in that case.
+func CheckCleanCheckout(ctx context.Context, ticket, checkout string) error {
+	if strings.TrimSpace(checkout) == "" {
+		return fmt.Errorf("cannot check Git cleanliness for ticket %q: checkout path is empty", ticket)
+	}
+	if _, err := os.Stat(checkout); err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil
+		}
+		return fmt.Errorf("cannot check Git cleanliness for ticket %q at %q: %w", ticket, checkout, err)
+	}
+
+	out, err := exec.CommandContext(ctx, "git", "-C", checkout, "status", "--porcelain=v1", "--untracked-files=all").CombinedOutput()
+	if err != nil {
+		detail := strings.TrimSpace(string(out))
+		if detail != "" {
+			return fmt.Errorf("cannot check Git cleanliness for ticket %q at %q: %w: %s", ticket, checkout, err, detail)
+		}
+		return fmt.Errorf("cannot check Git cleanliness for ticket %q at %q: %w", ticket, checkout, err)
+	}
+	if len(out) != 0 {
+		return fmt.Errorf("ticket %q checkout is dirty; commit required before runner cleanup", ticket)
+	}
+	return nil
+}

package/internal/runner/clean_test.go

@@ -0,0 +1,84 @@
+package runner
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestCheckCleanCheckoutRejectsGitChanges(t *testing.T) {
+	cases := map[string]func(t *testing.T, repo string){
+		"untracked": func(t *testing.T, repo string) {
+			writeFile(t, filepath.Join(repo, "untracked.txt"), "new\n")
+		},
+		"unstaged": func(t *testing.T, repo string) {
+			writeFile(t, filepath.Join(repo, "tracked.txt"), "changed\n")
+		},
+		"staged": func(t *testing.T, repo string) {
+			writeFile(t, filepath.Join(repo, "tracked.txt"), "changed\n")
+			runGit(t, repo, "add", "tracked.txt")
+		},
+	}
+	for name, makeDirty := range cases {
+		t.Run(name, func(t *testing.T) {
+			repo := newCleanCheckout(t)
+			makeDirty(t, repo)
+			err := CheckCleanCheckout(context.Background(), "PAY-101", repo)
+			if err == nil || !strings.Contains(err.Error(), "PAY-101") || !strings.Contains(err.Error(), "commit required") {
+				t.Fatalf("CheckCleanCheckout error = %v, want ticket and commit-required message", err)
+			}
+		})
+	}
+}
+
+func TestCheckCleanCheckoutAcceptsCleanAndMissingCheckouts(t *testing.T) {
+	repo := newCleanCheckout(t)
+	if err := CheckCleanCheckout(context.Background(), "PAY-101", repo); err != nil {
+		t.Fatalf("clean checkout returned %v", err)
+	}
+	if err := CheckCleanCheckout(context.Background(), "PAY-101", filepath.Join(t.TempDir(), "removed")); err != nil {
+		t.Fatalf("missing checkout returned %v, want idempotent success", err)
+	}
+}
+
+func TestCheckCleanCheckoutPropagatesGitStatusFailure(t *testing.T) {
+	dir := t.TempDir()
+	err := CheckCleanCheckout(context.Background(), "PAY-101", dir)
+	if err == nil {
+		t.Fatal("non-Git checkout was treated as clean")
+	}
+	if strings.Contains(err.Error(), "commit required") {
+		t.Fatalf("Git status failure was reported as dirty state: %v", err)
+	}
+}
+
+func newCleanCheckout(t *testing.T) string {
+	t.Helper()
+	repo := t.TempDir()
+	runGit(t, repo, "init", "-q", "-b", "main")
+	runGit(t, repo, "config", "user.email", "relay-flow@example.invalid")
+	runGit(t, repo, "config", "user.name", "Relay Flow")
+	writeFile(t, filepath.Join(repo, "tracked.txt"), "clean\n")
+	runGit(t, repo, "add", "tracked.txt")
+	runGit(t, repo, "commit", "-qm", "initial")
+	return repo
+}
+
+func writeFile(t *testing.T, path, contents string) {
+	t.Helper()
+	if err := os.WriteFile(path, []byte(contents), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func runGit(t *testing.T, repo string, args ...string) {
+	t.Helper()
+	cmd := exec.Command("git", args...)
+	cmd.Dir = repo
+	if output, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git %v: %v: %s", args, err, output)
+	}
+}