relay-flow 0.2.10-alpha → 0.3.0-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_test.go

@@ -14,7 +14,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const configuredPlugin = "relay-flow-plugin@0.2.10-alpha"
+const configuredPlugin = "relay-flow-plugin@0.3.0-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.10-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.3.0-alpha"
 
 type jsoncToken struct {
 	kind       byte

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)
+	}
+}

package/internal/runner/herdr/herdr.go

@@ -282,24 +282,24 @@ func (*adapter) SetEnvironmentStatus(context.Context, runner.Environment, string
 // ticketWorkspace resolves the ticket's currently open worktree workspace
 // without creating anything. found is false when the repository, the ticket
 // checkout, or its workspace is absent, which lets cleanup roll forward.
-func (a *adapter) ticketWorkspace(ctx context.Context, spec runner.RunSpec) (string, bool, error) {
+func (a *adapter) ticketWorkspace(ctx context.Context, spec runner.RunSpec) (string, string, bool, error) {
 	repoPath := normalizePath(spec.RepoPath)
 	if repoPath == "" {
-		return "", false, nil
+		return "", "", false, nil
 	}
 	listing, err := a.cli.WorktreeList(ctx, repoPath)
 	if err != nil {
 		if errors.Is(err, herdrcli.ErrNotGitWorktree) || errors.Is(err, herdrcli.ErrWorktreeNotFound) {
-			return "", false, nil
+			return "", "", false, nil
 		}
-		return "", false, err
+		return "", "", false, err
 	}
 	for _, worktree := range listing.Worktrees {
 		if worktree.Branch == spec.TicketKey && worktree.OpenWorkspaceID != "" {
-			return worktree.OpenWorkspaceID, true, nil
+			return worktree.OpenWorkspaceID, normalizePath(worktree.Path), true, nil
 		}
 	}
-	return "", false, nil
+	return "", "", false, nil
 }
 
 // --- Terminals ---
@@ -307,7 +307,7 @@ func (a *adapter) ticketWorkspace(ctx context.Context, spec runner.RunSpec) (str
 // DiscoverTerminal finds an existing live pane by its stable title during
 // explicit projection recovery. It never creates a workspace or pane.
 func (a *adapter) DiscoverTerminal(ctx context.Context, spec runner.RunSpec, title string) (runner.Terminal, bool, error) {
-	workspaceID, found, err := a.ticketWorkspace(ctx, spec)
+	workspaceID, _, found, err := a.ticketWorkspace(ctx, spec)
 	if err != nil || !found {
 		return runner.Terminal{}, false, err
 	}
@@ -549,7 +549,7 @@ func (a *adapter) CloseTerminal(ctx context.Context, terminal runner.Terminal) e
 func (a *adapter) CloseTerminals(ctx context.Context, spec runner.RunSpec) error {
 	attrs := []any{"ticket", spec.TicketKey, "runID", string(spec.RunID)}
 	logCall("close-terminals", attrs...)
-	workspaceID, found, err := a.ticketWorkspace(ctx, spec)
+	workspaceID, _, found, err := a.ticketWorkspace(ctx, spec)
 	if err != nil {
 		logOutcome("close-terminals", "error", attrs...)
 		return err
@@ -606,15 +606,29 @@ func (a *adapter) CloseTerminals(ctx context.Context, spec runner.RunSpec) error
 
 // CleanupRun releases the runner-owned resources for the run: node panes and
 // the ticket workspace. The Git worktree, its branch, and its files are
-// deliberately preserved; a later run reopens the same checkout.
+// deliberately preserved; a later run reopens the same checkout. The ticket
+// checkout must be clean before the workspace is closed.
 func (a *adapter) CleanupRun(ctx context.Context, spec runner.RunSpec) error {
 	attrs := []any{"ticket", spec.TicketKey, "runID", string(spec.RunID)}
 	logCall("cleanup-run", attrs...)
+	workspaceID, checkout, found, err := a.ticketWorkspace(ctx, spec)
+	if err != nil {
+		logOutcome("cleanup-run", "error", attrs...)
+		return err
+	}
+	if !found {
+		logOutcome("cleanup-run", "no-environment", attrs...)
+		return nil
+	}
+	if err := runner.CheckCleanCheckout(ctx, spec.TicketKey, checkout); err != nil {
+		logOutcome("cleanup-run", "error", attrs...)
+		return err
+	}
 	if err := a.CloseTerminals(ctx, spec); err != nil {
 		logOutcome("cleanup-run", "error", attrs...)
 		return err
 	}
-	workspaceID, found, err := a.ticketWorkspace(ctx, spec)
+	workspaceID, _, found, err = a.ticketWorkspace(ctx, spec)
 	if err != nil {
 		logOutcome("cleanup-run", "error", attrs...)
 		return err

package/internal/runner/herdr/herdr_test.go

@@ -739,6 +739,72 @@ func TestCleanupRunClosesTicketWorkspaceAndKeepsWorktree(t *testing.T) {
 	}
 }
 
+func TestCleanupRunBlocksDirtyCheckoutBeforeClosingHerdrResources(t *testing.T) {
+	repo := newGitRepo(t, "main")
+	if err := os.WriteFile(filepath.Join(repo, "dirty.txt"), []byte("uncommitted\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cli := cleanupClientAt(repo)
+	spec := runSpec()
+	spec.RepoPath = repo
+	if err := newAdapter(cli).CleanupRun(context.Background(), spec); err == nil || !strings.Contains(err.Error(), "commit required") {
+		t.Fatalf("CleanupRun error = %v, want commit-required dirty-check error", err)
+	}
+	if len(cli.closedPanes) != 0 || len(cli.closedWorkspaces) != 0 {
+		t.Fatalf("dirty cleanup touched Herdr resources: panes=%v workspaces=%v", cli.closedPanes, cli.closedWorkspaces)
+	}
+}
+
+func TestCleanupRunAllowsCleanCheckoutAndLaterRetry(t *testing.T) {
+	repo := newGitRepo(t, "main")
+	dirty := filepath.Join(repo, "dirty.txt")
+	if err := os.WriteFile(dirty, []byte("uncommitted\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cli := cleanupClientAt(repo)
+	spec := runSpec()
+	spec.RepoPath = repo
+	a := newAdapter(cli)
+	if err := a.CleanupRun(context.Background(), spec); err == nil {
+		t.Fatal("dirty CleanupRun succeeded")
+	}
+	if err := os.Remove(dirty); err != nil {
+		t.Fatal(err)
+	}
+	if err := a.CleanupRun(context.Background(), spec); err != nil {
+		t.Fatalf("clean retry CleanupRun = %v", err)
+	}
+	if len(cli.closedPanes) != 1 || len(cli.closedWorkspaces) != 1 {
+		t.Fatalf("clean retry resources: panes=%v workspaces=%v", cli.closedPanes, cli.closedWorkspaces)
+	}
+}
+
+func TestCleanupRunPropagatesGitStatusFailureBeforeClosingHerdrResources(t *testing.T) {
+	repo := t.TempDir()
+	cli := cleanupClientAt(repo)
+	spec := runSpec()
+	spec.RepoPath = repo
+	if err := newAdapter(cli).CleanupRun(context.Background(), spec); err == nil {
+		t.Fatal("CleanupRun treated Git status failure as clean")
+	}
+	if len(cli.closedPanes) != 0 || len(cli.closedWorkspaces) != 0 {
+		t.Fatalf("Git status failure touched Herdr resources: panes=%v workspaces=%v", cli.closedPanes, cli.closedWorkspaces)
+	}
+}
+
+func cleanupClientAt(repo string) *fakeClient {
+	return &fakeClient{
+		listing: herdrcli.WorktreeListing{
+			Source: herdrcli.WorktreeSource{RepoName: "payments", RepoRoot: repo, SourceCheckoutPath: repo},
+			Worktrees: []herdrcli.Worktree{
+				{Path: repo, Branch: "PAY-101", IsLinked: true, OpenWorkspaceID: "w2"},
+			},
+		},
+		tabs:  []herdrcli.Tab{{ID: "w2:t2", WorkspaceID: "w2", Label: "PAY-101:coding"}},
+		panes: []herdrcli.Pane{{ID: "w2:p2", WorkspaceID: "w2", TabID: "w2:t2", Label: "PAY-101:coding"}},
+	}
+}
+
 func TestCleanupRollsForwardWhenTicketWorktreeIsGone(t *testing.T) {
 	cases := map[string]*fakeClient{
 		"repository is not a git work tree": {listingErr: herdrcli.ErrNotGitWorktree},

package/internal/runner/orca/orca.go

@@ -457,14 +457,28 @@ func (a *adapter) CloseTerminals(ctx context.Context, spec runner.RunSpec) error
 }
 
 // CleanupRun removes all runner-owned run resources: terminals, then the
-// ticket worktree itself.
+// ticket worktree itself. The ticket checkout must be clean before either
+// resource is released.
 func (a *adapter) CleanupRun(ctx context.Context, spec runner.RunSpec) error {
 	slog.Debug("orca call", "op", "cleanup-run", "ticket", spec.TicketKey, "runID", string(spec.RunID))
+	env, ok, err := a.findEnvironment(ctx, spec)
+	if err != nil || !ok {
+		if err != nil {
+			slog.Info("orca outcome", "op", "cleanup-run", "ticket", spec.TicketKey, "result", "error", "error", sanitizeErr(err))
+		} else {
+			slog.Info("orca outcome", "op", "cleanup-run", "ticket", spec.TicketKey, "result", "no-environment")
+		}
+		return err
+	}
+	if err := runner.CheckCleanCheckout(ctx, spec.TicketKey, env.Path); err != nil {
+		slog.Info("orca outcome", "op", "cleanup-run", "ticket", spec.TicketKey, "result", "error", "error", sanitizeErr(err))
+		return err
+	}
 	if err := a.CloseTerminals(ctx, spec); err != nil {
 		slog.Info("orca outcome", "op", "cleanup-run", "ticket", spec.TicketKey, "result", "error", "error", sanitizeErr(err))
 		return err
 	}
-	env, ok, err := a.findEnvironment(ctx, spec)
+	env, ok, err = a.findEnvironment(ctx, spec)
 	if err != nil || !ok {
 		if err != nil {
 			slog.Info("orca outcome", "op", "cleanup-run", "ticket", spec.TicketKey, "result", "error", "error", sanitizeErr(err))