relay-flow 0.3.8-alpha → 0.3.9-alpha

package/README.md

@@ -24,13 +24,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.3.8-alpha
+opencode plugin relay-flow-plugin@0.3.9-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.8-alpha
+pi install npm:relay-flow-plugin@0.3.9-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -160,7 +160,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.3.8-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.9-alpha"]
 }
 ```
 
@@ -169,7 +169,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.3.8-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.9-alpha"]
 }
 ```
 
@@ -185,7 +185,7 @@ Pi plugin: install the same published package manually in Pi's global package
 settings before starting a Pi harness session:
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.8-alpha
+pi install npm:relay-flow-plugin@0.3.9-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves

package/internal/execution/goworkflows/activities.go

@@ -161,6 +161,17 @@ func (a *Activities) LoadNodeRuntime(ctx context.Context, id run.ID, node string
 	return a.Runs.loadNodeRuntime(ctx, id, node)
 }
 
+// LoadCancellationReason reads the operator reason persisted by the
+// cancellation CAS. It is an activity because workflow code cannot access
+// the relay projection directly.
+func (a *Activities) LoadCancellationReason(ctx context.Context, id run.ID) (string, error) {
+	r, err := a.Runs.get(ctx, id)
+	if err != nil {
+		return "", err
+	}
+	return r.LastError, nil
+}
+
 // 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. A stored

package/internal/execution/goworkflows/cancellation_test.go

@@ -0,0 +1,50 @@
+package goworkflows
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/cschleiden/go-workflows/backend"
+)
+
+func TestDetachedContextPreservesDeadline(t *testing.T) {
+	deadline := time.Now().Add(2 * time.Second)
+	parent, cancel := context.WithDeadline(context.Background(), deadline)
+	defer cancel()
+	detached, cleanup := detachedContext(parent)
+	defer cleanup()
+	cancel()
+	if err := detached.Err(); err != nil {
+		t.Fatalf("detached context inherited parent cancellation: %v", err)
+	}
+	got, ok := detached.Deadline()
+	if !ok || got.After(deadline.Add(10*time.Millisecond)) || got.Before(deadline.Add(-10*time.Millisecond)) {
+		t.Fatalf("detached deadline = %v, want approximately %v", got, deadline)
+	}
+}
+
+func TestIsMissingWorkflowInstanceOnlyMatchesConfirmedAbsence(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{name: "sql no rows", err: sql.ErrNoRows, want: true},
+		{name: "wrapped sql no rows", err: fmt.Errorf("lookup instance: %w", sql.ErrNoRows), want: true},
+		{name: "backend not found", err: backend.ErrInstanceNotFound, want: true},
+		{name: "wrapped backend not found", err: fmt.Errorf("cancel instance: %w", backend.ErrInstanceNotFound), want: true},
+		{name: "database locked", err: errors.New("database is locked"), want: false},
+		{name: "context canceled", err: errors.New("context canceled"), want: false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := isMissingWorkflowInstance(tt.err); got != tt.want {
+				t.Fatalf("isMissingWorkflowInstance(%v) = %v, want %v", tt.err, got, tt.want)
+			}
+		})
+	}
+}

package/internal/execution/goworkflows/engine.go

@@ -27,8 +27,10 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/harness"
 	"github.com/rajpopat27/relay-flow/internal/identity"
 	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/retry"
 	"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"
 )
 
@@ -61,6 +63,7 @@ type Engine struct {
 	runtime    run.RuntimePolicy
 
 	mu        sync.RWMutex
+	cancelMu  sync.Mutex                    // serializes cancellation history check + request
 	snapshots map[run.ID]*workflow.Workflow // in-memory cache; history is authoritative
 
 	workerCtx    context.Context
@@ -177,6 +180,11 @@ func (e *Engine) Start(ctx context.Context) error {
 	if err := e.actWorker.Start(e.workerCtx); err != nil {
 		return fmt.Errorf("start activity worker: %w", err)
 	}
+	// A cancellation request can outlive the engine instance that accepted it.
+	// Reconcile those projections before normal pollers start; a missing
+	// workflow instance is a confirmed terminal execution boundary, while
+	// other lookup failures remain retryable and are logged below.
+	e.reconcileCancelingRuns(ctx)
 	// Startup retention sweep (pre-poller window): remove old terminal
 	// projection rows and their engine histories; nonterminal runs stay.
 	cutoff := time.Now().Add(-e.retention)
@@ -202,6 +210,7 @@ func (e *Engine) registerActivities() error {
 		a.EnsureEnvironment,
 		a.SetEnvironmentStatus,
 		a.LoadNodeRuntime,
+		a.LoadCancellationReason,
 		a.EnsureNodeRuntime,
 		a.CloseTerminals,
 		a.CleanupRun,
@@ -462,26 +471,286 @@ func (e *Engine) workflowOf(ctx context.Context, id run.ID) (*workflow.Workflow,
 	return nil, fmt.Errorf("no workflow snapshot in history for run %s", id)
 }
 
-// CancelRun cancels the workflow instance; cleanup runs on a disconnected
-// workflow context and cannot interrupt an already-running activity.
+// CancelRun requests cancellation of the durable workflow. The projection
+// transition is compare-and-set: a concurrent completion wins if it reaches a
+// terminal state first, while a persisted canceling state is the durable
+// request that startup reconciliation retries.
 func (e *Engine) CancelRun(ctx context.Context, id run.ID, reason string) error {
-	if _, err := e.runs.get(ctx, id); err != nil {
+	r, err := e.runs.beginCancellation(ctx, id, reason)
+	if err != nil {
 		return fmt.Errorf("resolve run %s: %w", id, err)
 	}
-	if err := e.runs.updateState(ctx, id, run.StateCanceling, reason, nil); err != nil {
+	if r.State == run.StateCompleted || r.State == run.StateCanceled {
+		return nil
+	}
+	if r.State != run.StateCanceling {
+		return fmt.Errorf("cancel %s: state changed to %s", id, r.State)
+	}
+	// The reason persisted by the first successful CAS is authoritative for
+	// every later cancellation request.
+	return e.reconcileCancellation(ctx, r, r.LastError)
+}
+
+// isMissingWorkflowInstance identifies only confirmed absence of the active
+// go-workflows execution. Database and context failures remain retryable.
+func isMissingWorkflowInstance(err error) bool {
+	return errors.Is(err, sql.ErrNoRows) || errors.Is(err, backend.ErrInstanceNotFound)
+}
+
+// detachedContext preserves a caller deadline while detaching cancellation
+// from the caller. Startup cleanup must not be able to outlive its bounded
+// reconciliation window.
+func detachedContext(ctx context.Context) (context.Context, context.CancelFunc) {
+	base := context.WithoutCancel(ctx)
+	if deadline, ok := ctx.Deadline(); ok {
+		return context.WithDeadline(base, deadline)
+	}
+	return base, func() {}
+}
+
+// lookupInstance returns the active execution when present. If only a finished
+// row remains, finished is true; a missing row is the only absence outcome.
+func (e *Engine) lookupInstance(ctx context.Context, id run.ID) (*goworkflow.Instance, bool, error) {
+	var execID string
+	var state int
+	err := e.db.QueryRowContext(ctx, `
+		SELECT execution_id, state FROM instances WHERE id = ?
+		ORDER BY CASE WHEN state = 0 THEN 0 ELSE 1 END, rowid DESC LIMIT 1`, string(id)).Scan(&execID, &state)
+	if err != nil {
+		return nil, false, fmt.Errorf("workflow instance %s not found: %w", id, err)
+	}
+	return &goworkflow.Instance{InstanceID: string(id), ExecutionID: execID}, state != 0, nil
+}
+
+// reconcileCancellation retries the durable cancellation request while an
+// execution is active and reconciles finished/missing executions separately.
+func (e *Engine) reconcileCancellation(ctx context.Context, r run.Run, reason string) error {
+	inst, finished, err := e.lookupInstance(ctx, r.ID)
+	if err != nil {
+		if isMissingWorkflowInstance(err) {
+			return e.finalizeMissingCancellation(ctx, r, reason)
+		}
+		return fmt.Errorf("resolve workflow instance: %w", err)
+	}
+	if finished {
+		return e.reconcileFinishedCancellation(ctx, r, inst, reason)
+	}
+	if e.client == nil {
+		return errors.New("workflow engine is not started")
+	}
+	if err := e.requestCancellation(ctx, inst); err != nil {
+		if isMissingWorkflowInstance(err) {
+			return e.finalizeMissingCancellation(ctx, r, reason)
+		}
 		return err
 	}
-	inst, err := e.instance(ctx, id)
+	return nil
+}
+
+// requestCancellation checks durable history and appends at most one
+// cancellation event for an execution. The mutex closes the check/request
+// race between concurrent operator calls in this process; the relay lock
+// prevents another relay-flow server from owning the same database.
+func (e *Engine) requestCancellation(ctx context.Context, inst *goworkflow.Instance) error {
+	e.cancelMu.Lock()
+	defer e.cancelMu.Unlock()
+	var requested int
+	if err := e.db.QueryRowContext(ctx, `
+		SELECT EXISTS(
+			SELECT 1 FROM history
+			WHERE instance_id = ? AND execution_id = ? AND event_type = ?
+			UNION ALL
+			SELECT 1 FROM pending_events
+			WHERE instance_id = ? AND execution_id = ? AND event_type = ?
+		)`,
+		inst.InstanceID, inst.ExecutionID, history.EventType_WorkflowExecutionCanceled,
+		inst.InstanceID, inst.ExecutionID, history.EventType_WorkflowExecutionCanceled,
+	).Scan(&requested); err != nil {
+		return fmt.Errorf("inspect cancellation history: %w", err)
+	}
+	if requested != 0 {
+		return nil
+	}
+	return e.client.CancelWorkflowInstance(ctx, inst)
+}
+
+// finalizeMissingCancellation performs the same roll-forward cleanup as the
+// workflow's disconnected cancellation path when the workflow instance has
+// genuinely disappeared. It intentionally does not recreate an execution.
+func (e *Engine) finalizeMissingCancellation(ctx context.Context, r run.Run, reason string) error {
+	cleanupCtx, cleanupCancel := detachedContext(ctx)
+	defer cleanupCancel()
+	current, err := e.runs.get(cleanupCtx, r.ID)
+	if err != nil {
+		return fmt.Errorf("reconcile canceled run %s projection: %w", r.ID, err)
+	}
+	if current.State == run.StateCompleted || current.State == run.StateCanceled {
+		return nil
+	}
+	if current.State != run.StateCanceling {
+		return fmt.Errorf("reconcile canceled run %s: state changed to %s", r.ID, current.State)
+	}
+	if inst, finished, lookupErr := e.lookupInstance(cleanupCtx, r.ID); lookupErr == nil {
+		if finished {
+			return e.reconcileFinishedCancellation(cleanupCtx, current, inst, reason)
+		}
+		return fmt.Errorf("reconcile canceled run %s: workflow instance reappeared", r.ID)
+	} else if !isMissingWorkflowInstance(lookupErr) {
+		return fmt.Errorf("reconcile canceled run %s instance lookup: %w", r.ID, lookupErr)
+	}
+	return e.finalizeCancellationEffects(cleanupCtx, current, reason)
+}
+
+// finalizeCancellationEffects is shared by missing and already-canceled
+// engine executions. The final projection transition is conditional so a
+// concurrent terminal projection cannot be overwritten.
+func (e *Engine) finalizeCancellationEffects(ctx context.Context, r run.Run, reason string) error {
+	if r.State == run.StateCompleted || r.State == run.StateCanceled {
+		return nil
+	}
+	if r.State != run.StateCanceling {
+		return fmt.Errorf("finalize canceled run %s: state changed to %s", r.ID, r.State)
+	}
+	repoInfo, ok := e.activities.Repos.Get(r.Repo)
+	if !ok {
+		return fmt.Errorf("reconcile canceled run %s: repo %q is no longer registered", r.ID, r.Repo)
+	}
+	work := run.Work{
+		RunID:     r.ID,
+		LogicalID: r.LogicalID,
+		AttemptID: r.AttemptID,
+		Repo:      r.Repo,
+		Workflow:  r.Workflow,
+		Parent:    r.Ticket,
+		Runtime:   e.runtime,
+	}
+	if reason == "" {
+		reason = "operator requested cancellation"
+	}
+	if err := e.activities.FinalizeNodeRuntimes(ctx, work, repoInfo.Path, e.runtime); err != nil {
+		return fmt.Errorf("finalize canceled run %s terminals: %w", r.ID, err)
+	}
+	markerID := r.LogicalID
+	if markerID == "" {
+		markerID = r.ID
+	}
+	if err := e.activities.Comment(ctx, r.Repo, run.CommentWork{
+		RunID:  r.ID,
+		Item:   task.Target{Parent: r.Ticket},
+		Body:   "Run canceled: " + reason,
+		Marker: run.CancellationMarker(markerID),
+	}); err != nil {
+		return fmt.Errorf("finalize canceled run %s comment: %w", r.ID, err)
+	}
+	finished := time.Now().UTC()
+	updated, err := e.runs.updateStateIf(ctx, r.ID, run.StateCanceling, run.StateCanceled, "", &finished)
 	if err != nil {
-		return fmt.Errorf("cancel %s: %w", id, err)
+		return fmt.Errorf("finalize canceled run %s projection: %w", r.ID, err)
 	}
-	if err := e.client.CancelWorkflowInstance(ctx, inst); err != nil {
-		return fmt.Errorf("cancel %s: %w", id, err)
+	if !updated {
+		latest, getErr := e.runs.get(ctx, r.ID)
+		if getErr == nil && (latest.State == run.StateCanceled || latest.State == run.StateCompleted) {
+			return nil
+		}
+		if getErr != nil {
+			return fmt.Errorf("finalize canceled run %s projection after race: %w", r.ID, getErr)
+		}
+		return fmt.Errorf("finalize canceled run %s: state changed to %s", r.ID, latest.State)
 	}
+	slog.Info("run canceled", "ticket", r.Ticket.Key, "runID", string(r.ID),
+		"repo", r.Repo, "workflow", r.Workflow, "state", run.StateCanceled)
 	return nil
 }
 
-// instance resolves the current execution for the durable run ID.
+// reconcileFinishedCancellation reads the terminal engine event before
+// deciding whether a canceling projection should become completed or canceled.
+func (e *Engine) reconcileFinishedCancellation(ctx context.Context, r run.Run, inst *goworkflow.Instance, reason string) error {
+	if e.backend == nil {
+		return errors.New("workflow backend is not started")
+	}
+	events, err := e.backend.GetWorkflowInstanceHistory(ctx, inst, nil)
+	if err != nil {
+		return fmt.Errorf("read finished workflow history: %w", err)
+	}
+	var finishedEvent *history.Event
+	canceledBeforeFinish := false
+	for _, event := range events {
+		switch event.Type {
+		case history.EventType_WorkflowExecutionCanceled:
+			// TicketWorkflow records this cancellation request first; after
+			// cancelCleanup returns, go-workflows may append a normal
+			// WorkflowExecutionFinished event. The earlier cancellation event
+			// remains authoritative for relay-flow semantics.
+			if finishedEvent == nil {
+				canceledBeforeFinish = true
+			}
+		case history.EventType_WorkflowExecutionFinished:
+			if finishedEvent == nil {
+				finishedEvent = event
+			}
+		case history.EventType_WorkflowExecutionTerminated:
+			return fmt.Errorf("workflow %s terminated without a cancellation or completion result", r.ID)
+		}
+	}
+	if canceledBeforeFinish {
+		return e.finalizeCancellationEffects(ctx, r, reason)
+	}
+	if finishedEvent == nil {
+		return fmt.Errorf("finished workflow %s has no terminal history event", r.ID)
+	}
+	{
+		finished := finishedEvent.Timestamp
+		updated, err := e.runs.updateStateIf(ctx, r.ID, run.StateCanceling, run.StateCompleted, "", &finished)
+		if err != nil {
+			return fmt.Errorf("reconcile completed run %s projection: %w", r.ID, err)
+		}
+		if !updated {
+			latest, getErr := e.runs.get(ctx, r.ID)
+			if getErr == nil && (latest.State == run.StateCompleted || latest.State == run.StateCanceled) {
+				return nil
+			}
+			if getErr != nil {
+				return fmt.Errorf("reconcile completed run %s projection after race: %w", r.ID, getErr)
+			}
+			return fmt.Errorf("reconcile completed run %s: state changed to %s", r.ID, latest.State)
+		}
+		return nil
+	}
+}
+
+// reconcileCancelingRuns retries the durable cancellation request for every
+// stale canceling projection. An active instance is not skipped: its cancel
+// event is re-submitted until the workflow accepts it.
+func (e *Engine) reconcileCancelingRuns(ctx context.Context) {
+	active := true
+	runs, err := e.runs.list(ctx, run.Filter{Active: &active})
+	if err != nil {
+		slog.Warn("reconcile canceling runs unavailable", "error", err)
+		return
+	}
+	for _, r := range runs {
+		if r.State != run.StateCanceling {
+			continue
+		}
+		if err := e.retryStartupCancellation(ctx, r); err != nil {
+			slog.Warn("reconcile canceling run failed", "runID", r.ID, "error", err)
+		}
+	}
+}
+
+// retryStartupCancellation gives a durable canceling projection a bounded
+// startup retry window. Normal polling deliberately does not recreate or
+// advance canceling runs, so an active execution must receive its cancel
+// event here or remain visibly retryable for the next restart.
+func (e *Engine) retryStartupCancellation(ctx context.Context, r run.Run) error {
+	retryCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 5*time.Second)
+	defer cancel()
+	return retry.Do(retryCtx, retry.DefaultBackoffPolicy, func() error {
+		return e.reconcileCancellation(retryCtx, r, r.LastError)
+	})
+}
+
+// instance resolves the current active execution for the durable run ID.
 func (e *Engine) instance(ctx context.Context, id run.ID) (*goworkflow.Instance, error) {
 	var execID string
 	err := e.db.QueryRowContext(ctx,

package/internal/execution/goworkflows/fakes_test.go

@@ -226,7 +226,16 @@ func (s *fakeTaskSystem) Comment(_ context.Context, target task.Target, body, ma
 	if target.Mailbox != nil {
 		key = target.Mailbox.Key
 	}
-	if s.failComments {
+	s.mu.Lock()
+	for _, comment := range s.comments {
+		if comment.Key == key && comment.Marker == marker {
+			s.mu.Unlock()
+			return nil
+		}
+	}
+	fail := s.failComments
+	s.mu.Unlock()
+	if fail {
 		s.log.add("commentFail:" + key)
 		return errTransient
 	}

package/internal/execution/goworkflows/interpreter.go

@@ -75,7 +75,23 @@ func (a *Activities) TicketWorkflow(ctx goworkflow.Context, start run.Start) err
 			WorkflowTaskConfig: start.Workflow.TaskConfig,
 			Runtime:            start.Runtime,
 		}
-		return a.cancelCleanup(ctx, work, start.RepoPath, "canceled")
+		// Cancellation events do not carry relay-flow's operator reason. Read
+		// the reason persisted by CancelRun through the durable disconnected
+		// retry path so cleanup cannot write a permanently wrong comment when
+		// the projection is temporarily unavailable.
+		dctx := goworkflow.NewDisconnectedContext(ctx)
+		reason, reasonErr := retryLoop(dctx, start.ID, a, work, "",
+			func(ctx2 goworkflow.Context) goworkflow.Future[string] {
+				return goworkflow.ExecuteActivity[string](ctx2, noNativeRetries,
+					a.LoadCancellationReason, start.ID)
+			})
+		if reasonErr != nil {
+			return reasonErr
+		}
+		if reason == "" {
+			reason = "canceled"
+		}
+		return a.cancelCleanup(ctx, work, start.RepoPath, reason)
 	}
 	return err
 }

package/internal/execution/goworkflows/projection.go

@@ -46,6 +46,14 @@ func (p *RunProjection) updateState(ctx context.Context, id run.ID, state run.St
 	return p.shared().UpdateState(ctx, id, state, lastErr, finished)
 }
 
+func (p *RunProjection) beginCancellation(ctx context.Context, id run.ID, reason string) (run.Run, error) {
+	return p.shared().BeginCancellation(ctx, id, reason)
+}
+
+func (p *RunProjection) updateStateIf(ctx context.Context, id run.ID, expected, state run.State, lastErr string, finished *time.Time) (bool, error) {
+	return p.shared().UpdateStateIf(ctx, id, expected, state, lastErr, finished)
+}
+
 func (p *RunProjection) updateRetry(ctx context.Context, id run.ID, status *run.RetryStatus) error {
 	return p.shared().UpdateRetry(ctx, id, status)
 }

package/internal/execution/goworkflows/recovery_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/cschleiden/go-workflows/backend/history"
 	"github.com/rajpopat27/relay-flow/internal/execution/goworkflows"
 	"github.com/rajpopat27/relay-flow/internal/identity"
 	recoverpkg "github.com/rajpopat27/relay-flow/internal/recover"
@@ -200,14 +201,19 @@ func TestCancelRun(t *testing.T) {
 	// Exactly one parent cancellation comment with the stable marker.
 	wantMarker := string(rid) + ":cancellation"
 	var cancelComments int
+	var cancellationBody string
 	for _, c := range sys.commentBodies("PAY-101") {
 		if c.Marker == wantMarker {
 			cancelComments++
+			cancellationBody = c.Body
 		}
 	}
 	if cancelComments != 1 {
 		t.Fatalf("cancellation comments = %d, want 1 with marker %q", cancelComments, wantMarker)
 	}
+	if !strings.Contains(cancellationBody, "Run canceled: no longer needed") {
+		t.Fatalf("cancellation comment = %q, want persisted operator reason", cancellationBody)
+	}
 
 	// Mailbox statuses/history unchanged: the in-flight coding mailbox was
 	// not completed by cancellation.
@@ -220,6 +226,482 @@ func TestCancelRun(t *testing.T) {
 	}
 }
 
+func TestCancelRunFinalizesWhenWorkflowInstanceIsMissing(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	deps := goworkflows.Dependencies{
+		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: newFakeHarness(log),
+		Runtime: &run.RuntimePolicy{},
+	}
+	dbPath := filepath.Join(t.TempDir(), "state.db")
+	first, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := first.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	rid, err := startRun(first, linearWorkflow(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	if err := first.Shutdown(shutdownCtx); err != nil {
+		t.Fatal(err)
+	}
+	cancel()
+
+	// Simulate the cancellation crash boundary: the relay projection has a
+	// run, but the active go-workflows instance is gone.
+	db, err := sql.Open("sqlite", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`DELETE FROM instances WHERE id = ?`, string(rid)); err != nil {
+		db.Close()
+		t.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	second, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = second.Shutdown(context.Background()) }()
+	sys.failComments = true
+	if err := second.CancelRun(context.Background(), rid, "operator canceled"); err == nil {
+		t.Fatal("CancelRun succeeded despite a cancellation-comment failure")
+	}
+	failed, err := second.GetRun(context.Background(), rid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if failed.State != run.StateCanceling || failed.LastError != "operator canceled" {
+		t.Fatalf("failed cancellation projection = %+v, want canceling with original reason", failed)
+	}
+	sys.failComments = false
+	if err := second.CancelRun(context.Background(), rid, "replacement reason"); err != nil {
+		t.Fatalf("CancelRun with missing workflow instance: %v", err)
+	}
+	got, err := second.GetRun(context.Background(), rid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.State != run.StateCanceled {
+		t.Fatalf("state = %q, want canceled", got.State)
+	}
+	active, err := second.HasActiveWorkflow(context.Background(), "basicFlow")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if active {
+		t.Fatal("canceled run is still counted as an active workflow")
+	}
+	if fr.liveTerminals() != 0 {
+		t.Fatalf("missing-instance cancellation left %d live terminals", fr.liveTerminals())
+	}
+	comments := sys.commentBodies("PAY-101")
+	if len(comments) != 1 || comments[0].Marker != string(rid)+":cancellation" {
+		t.Fatalf("cancellation comments = %#v, want one stable cancellation marker", comments)
+	}
+	if err := second.CancelRun(context.Background(), rid, "repeated cancellation"); err != nil {
+		t.Fatalf("repeated cancellation: %v", err)
+	}
+	if got, err := second.GetRun(context.Background(), rid); err != nil || got.State != run.StateCanceled {
+		t.Fatalf("repeated cancellation changed state: run=%+v err=%v", got, err)
+	}
+}
+
+func TestStartReconcilesCancelingRunWithoutWorkflowInstance(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	deps := goworkflows.Dependencies{
+		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: newFakeHarness(log),
+		Runtime: &run.RuntimePolicy{},
+	}
+	dbPath := filepath.Join(t.TempDir(), "state.db")
+	first, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := first.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	rid, err := startRun(first, linearWorkflow(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	if err := first.Shutdown(shutdownCtx); err != nil {
+		t.Fatal(err)
+	}
+	cancel()
+
+	db, err := sql.Open("sqlite", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`UPDATE relay_runs SET state = ?, last_error = ? WHERE id = ?`,
+		string(run.StateCanceling), "operator canceled", string(rid)); err != nil {
+		db.Close()
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`DELETE FROM instances WHERE id = ?`, string(rid)); err != nil {
+		db.Close()
+		t.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	second, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := second.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = second.Shutdown(context.Background()) }()
+	got, err := second.GetRun(context.Background(), rid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.State != run.StateCanceled {
+		t.Fatalf("startup reconciliation state = %q, want canceled", got.State)
+	}
+	active, err := second.HasActiveWorkflow(context.Background(), "basicFlow")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if active {
+		t.Fatal("startup-reconciled run is still counted as active")
+	}
+	if len(sys.commentBodies("PAY-101")) != 1 {
+		t.Fatalf("startup reconciliation comments = %d, want one", len(sys.commentBodies("PAY-101")))
+	}
+}
+
+func TestStartRetriesCancellationForExistingWorkflowInstance(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	deps := goworkflows.Dependencies{
+		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: newFakeHarness(log),
+		Runtime: &run.RuntimePolicy{},
+	}
+	dbPath := filepath.Join(t.TempDir(), "state.db")
+	first, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := first.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	rid, err := startRun(first, linearWorkflow(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	if err := first.Shutdown(shutdownCtx); err != nil {
+		t.Fatal(err)
+	}
+	cancel()
+
+	// Leave the engine instance active but persist the cancellation request as
+	// if the process died after the projection write and before the cancel RPC.
+	db, err := sql.Open("sqlite", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`UPDATE relay_runs SET state = ?, last_error = ? WHERE id = ?`,
+		string(run.StateCanceling), "startup cancellation", string(rid)); err != nil {
+		db.Close()
+		t.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	second, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := second.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = second.Shutdown(context.Background()) }()
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := second.GetRun(context.Background(), rid)
+		return r.State == run.StateCanceled
+	})
+	if len(sys.commentBodies("PAY-101")) != 1 {
+		t.Fatalf("startup cancellation comments = %d, want one", len(sys.commentBodies("PAY-101")))
+	}
+}
+
+func TestStartDistinguishesFinishedWorkflowFromMissingWorkflow(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	deps := goworkflows.Dependencies{
+		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: newFakeHarness(log),
+		Runtime: &run.RuntimePolicy{},
+	}
+	dbPath := filepath.Join(t.TempDir(), "state.db")
+	first, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := first.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	rid, err := startRun(first, linearWorkflow(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	if _, err := first.SubmitReport(context.Background(), reportRequest(rid, "coding", successReport("end"))); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.State == run.StateCompleted
+	})
+	waitFor(t, 10*time.Second, func() bool {
+		db, err := sql.Open("sqlite", dbPath)
+		if err != nil {
+			return false
+		}
+		defer db.Close()
+		var state int
+		if err := db.QueryRow(`SELECT state FROM instances WHERE id = ?`, string(rid)).Scan(&state); err != nil {
+			return false
+		}
+		return state != 0
+	})
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	if err := first.Shutdown(shutdownCtx); err != nil {
+		t.Fatal(err)
+	}
+	cancel()
+
+	// Corrupt only the relay projection into canceling. The finished engine
+	// row/history must win; this must not create a cancellation comment.
+	db, err := sql.Open("sqlite", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`UPDATE relay_runs SET state = ?, last_error = ?, finished_at = NULL WHERE id = ?`,
+		string(run.StateCanceling), "late cancellation", string(rid)); err != nil {
+		db.Close()
+		t.Fatal(err)
+	}
+	// Make the engine fixture unambiguously finished while retaining its
+	// history, so startup must inspect the terminal event rather than treating
+	// the row as a missing active execution.
+	if _, err := db.Exec(`UPDATE instances SET state = 2, completed_at = CURRENT_TIMESTAMP WHERE id = ?`, string(rid)); err != nil {
+		db.Close()
+		t.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	second, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := second.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = second.Shutdown(context.Background()) }()
+	got, err := second.GetRun(context.Background(), rid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.State != run.StateCompleted {
+		t.Fatalf("finished workflow was reconciled to %q, want completed", got.State)
+	}
+	if comments := sys.commentBodies("PAY-101"); len(comments) != 0 {
+		t.Fatalf("finished workflow received cancellation comments: %#v", comments)
+	}
+}
+
+func TestStartReconcilesCanceledWorkflowHistoryAsCanceled(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	deps := goworkflows.Dependencies{
+		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: newFakeHarness(log),
+		Runtime: &run.RuntimePolicy{},
+	}
+	dbPath := filepath.Join(t.TempDir(), "state.db")
+	first, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := first.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	rid, err := startRun(first, linearWorkflow(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	if err := first.CancelRun(context.Background(), rid, "history cancellation"); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.State == run.StateCanceled
+	})
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	if err := first.Shutdown(shutdownCtx); err != nil {
+		t.Fatal(err)
+	}
+	cancel()
+
+	db, err := sql.Open("sqlite", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`UPDATE relay_runs SET state = ?, last_error = ?, finished_at = NULL WHERE id = ?`,
+		string(run.StateCanceling), "history cancellation", string(rid)); err != nil {
+		db.Close()
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`UPDATE instances SET state = 2, completed_at = CURRENT_TIMESTAMP WHERE id = ?`, string(rid)); err != nil {
+		db.Close()
+		t.Fatal(err)
+	}
+	if err := db.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	second, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := second.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = second.Shutdown(context.Background()) }()
+	got, err := second.GetRun(context.Background(), rid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.State != run.StateCanceled {
+		t.Fatalf("canceled workflow history was reconciled to %q, want canceled", got.State)
+	}
+	if comments := sys.commentBodies("PAY-101"); len(comments) != 1 {
+		t.Fatalf("cancellation comments = %d, want one idempotent comment", len(comments))
+	}
+}
+
+func TestRepeatedCancellationDoesNotAppendCancellationEvents(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	deps := goworkflows.Dependencies{
+		Repos: repoRegistryWith("payments", sys), Runner: fr, Harness: newFakeHarness(log),
+		Runtime: &run.RuntimePolicy{},
+	}
+	dbPath := filepath.Join(t.TempDir(), "state.db")
+	first, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := first.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	rid, err := startRun(first, linearWorkflow(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	sys.failComments = true
+	if err := first.CancelRun(context.Background(), rid, "first reason"); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 15*time.Second, func() bool {
+		r, _ := first.GetRun(context.Background(), rid)
+		return r.State == run.StateCanceling
+	})
+	if err := first.CancelRun(context.Background(), rid, "second reason"); err != nil {
+		t.Fatal(err)
+	}
+	if got := countWorkflowEvents(t, dbPath, rid, history.EventType_WorkflowExecutionCanceled); got != 1 {
+		t.Fatalf("cancellation events after repeated cancel = %d, want 1", got)
+	}
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	if err := first.Shutdown(shutdownCtx); err != nil {
+		t.Fatal(err)
+	}
+	cancel()
+
+	second, err := goworkflows.New(dbPath, deps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := second.Start(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = second.Shutdown(context.Background()) }()
+	// Let the already-persisted cancellation event drive cleanup after the
+	// restart; startup must not append another event.
+	sys.failComments = false
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := second.GetRun(context.Background(), rid)
+		return r.State == run.StateCanceled
+	})
+	if got := countWorkflowEvents(t, dbPath, rid, history.EventType_WorkflowExecutionCanceled); got != 1 {
+		t.Fatalf("cancellation events after restart = %d, want 1", got)
+	}
+}
+
+func countWorkflowEvents(t *testing.T, dbPath string, id run.ID, eventType history.EventType) int {
+	t.Helper()
+	db, err := sql.Open("sqlite", dbPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	var count int
+	if err := db.QueryRow(`
+		SELECT
+			(SELECT COUNT(*) FROM history WHERE instance_id = ? AND event_type = ?)
+			+ (SELECT COUNT(*) FROM pending_events WHERE instance_id = ? AND event_type = ?)`,
+		string(id), int(eventType), string(id), int(eventType)).Scan(&count); err != nil {
+		t.Fatal(err)
+	}
+	return count
+}
+
 func TestExplicitRestartCreatesFreshAttemptFromStart(t *testing.T) {
 	log := newEventLog()
 	sys := newFakeTaskSystem(log)

package/internal/execution/projection/detail_test.go

@@ -206,6 +206,44 @@ func TestCompletedRunFinalizesActiveStepWhenFinalUpsertIsMissing(t *testing.T) {
 	}
 }
 
+func TestCancellationFencePreservesReasonAndRejectsLateCompletion(t *testing.T) {
+	ctx := context.Background()
+	p, _ := openProjection(t)
+	start := projectionStart("cancel-fence", "PAY-CANCEL-FENCE")
+	if err := p.InsertStart(ctx, start, time.Now().UTC()); err != nil {
+		t.Fatal(err)
+	}
+	first, err := p.BeginCancellation(ctx, start.ID, "first reason")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first.State != run.StateCanceling || first.LastError != "first reason" {
+		t.Fatalf("first cancellation = %+v", first)
+	}
+	second, err := p.BeginCancellation(ctx, start.ID, "replacement reason")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if second.State != run.StateCanceling || second.LastError != "first reason" {
+		t.Fatalf("repeated cancellation overwrote reason: %+v", second)
+	}
+	if err := p.UpdateState(ctx, start.ID, run.StateCompleted, "", nil); err != nil {
+		t.Fatal(err)
+	}
+	stillCanceling, err := p.Get(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if stillCanceling.State != run.StateCanceling || stillCanceling.LastError != "first reason" {
+		t.Fatalf("late completion overwrote cancellation: %+v", stillCanceling)
+	}
+	finished := time.Now().UTC()
+	updated, err := p.UpdateStateIf(ctx, start.ID, run.StateCanceling, run.StateCanceled, "", &finished)
+	if err != nil || !updated {
+		t.Fatalf("canceling finalization updated=%v err=%v", updated, err)
+	}
+}
+
 func TestCanceledRunFinalizesCurrentStepTiming(t *testing.T) {
 	ctx := context.Background()
 	p, _ := openProjection(t)

package/internal/execution/projection/projection.go

@@ -257,24 +257,69 @@ func (p *RunProjection) insertStart(ctx context.Context, s run.Start, now time.T
 }
 
 func (p *RunProjection) updateState(ctx context.Context, id run.ID, state run.State, lastErr string, finished *time.Time) error {
+	_, err := p.updateStateCAS(ctx, id, nil, state, lastErr, finished)
+	return err
+}
+
+// beginCancellation atomically claims cancellation of a nonterminal run. A
+// run already in canceling keeps its original reason; completed/canceled runs
+// are never moved backwards. The returned row is read after the conditional
+// update so concurrent cancel/complete callers observe the winner.
+func (p *RunProjection) beginCancellation(ctx context.Context, id run.ID, reason string) (run.Run, error) {
+	_, err := p.DB.ExecContext(ctx, `
+		UPDATE relay_runs SET state = ?, last_error = ?, updated_at = ?
+		WHERE id = ? AND state NOT IN ('completed', 'canceled', 'canceling')`,
+		string(run.StateCanceling), reason, time.Now().UTC(), string(id))
+	if err != nil {
+		return run.Run{}, err
+	}
+	return p.get(ctx, id)
+}
+
+func (p *RunProjection) updateStateCAS(ctx context.Context, id run.ID, expected *run.State, state run.State, lastErr string, finished *time.Time) (bool, error) {
 	terminal := state == run.StateCompleted || state == run.StateCanceled
 	now := time.Now().UTC()
-	_, err := p.DB.ExecContext(ctx, `
+	query := `
 		UPDATE relay_runs SET state = ?, last_error = ?, updated_at = ?, finished_at = COALESCE(?, finished_at),
 			retry_error = CASE WHEN ? THEN NULL ELSE retry_error END,
 			retry_attempt = CASE WHEN ? THEN NULL ELSE retry_attempt END,
 			next_retry_at = CASE WHEN ? THEN NULL ELSE next_retry_at END
-		WHERE id = ?`,
-		string(state), lastErr, now, finished, terminal, terminal, terminal, string(id))
+		WHERE id = ?`
+	args := []any{
+		string(state), lastErr, now, finished, terminal, terminal, terminal,
+		string(id),
+	}
+	if expected == nil {
+		// Ordinary workflow projection updates are fenced after cancellation or
+		// any terminal state has won. Explicit compare-and-set callers below
+		// are allowed to reconcile a known canceling row to its inspected
+		// terminal engine result.
+		query += ` AND NOT (
+			(state = 'canceling' AND ? NOT IN ('canceling', 'canceled'))
+			OR (state IN ('completed', 'canceled') AND state <> ?)
+		)`
+		args = append(args, string(state), string(state))
+	} else {
+		query += ` AND state = ? AND NOT (state IN ('completed', 'canceled') AND state <> ?)`
+		args = append(args, string(*expected), string(state))
+	}
+	result, err := p.DB.ExecContext(ctx, query, args...)
 	if err != nil {
-		return err
+		return false, err
+	}
+	updated, err := result.RowsAffected()
+	if err != nil {
+		return false, err
+	}
+	if updated != 1 {
+		return false, nil
 	}
 	// Keep the derived timeline useful during retries and cancellation without
 	// making it an execution authority. Identify one active row first; a
 	// repeated terminal update with no active row is a no-op for the timeline.
 	stepStatus := stepStatusForRunState(state)
 	if stepStatus == "" {
-		return nil
+		return true, nil
 	}
 	var sequence int64
 	var startedAt sql.NullTime
@@ -283,14 +328,14 @@ func (p *RunProjection) updateState(ctx context.Context, id run.ID, state run.St
 		WHERE run_id = ? AND status IN ('running', 'waiting', 'blocked')
 		ORDER BY sequence DESC LIMIT 1`, string(id)).Scan(&sequence, &startedAt)
 	if errors.Is(lookupErr, sql.ErrNoRows) {
-		return nil
+		return true, nil
 	}
 	if lookupErr != nil {
 		// relay_run_steps is display/cache data. The authoritative relay_runs
 		// state update above has already succeeded and must not be retried just
 		// because this optional projection is unavailable.
 		slog.Warn("step projection state lookup unavailable", "runID", string(id), "state", state, "error", lookupErr)
-		return nil
+		return true, nil
 	}
 	var stepFinished any
 	if terminal {
@@ -300,7 +345,7 @@ func (p *RunProjection) updateState(ctx context.Context, id run.ID, state run.St
 			stepFinished = now
 		}
 	}
-	result, err := p.DB.ExecContext(ctx, `
+	result, err = p.DB.ExecContext(ctx, `
 		UPDATE relay_run_steps SET status = ?, message = CASE WHEN ? <> '' THEN ? ELSE message END,
 			finished_at = CASE WHEN ? THEN COALESCE(finished_at, ?) ELSE finished_at END
 		WHERE run_id = ? AND sequence = ? AND status IN ('running', 'waiting', 'blocked')`,
@@ -308,11 +353,11 @@ func (p *RunProjection) updateState(ctx context.Context, id run.ID, state run.St
 		string(id), sequence)
 	if err != nil {
 		slog.Warn("step projection state update unavailable", "runID", string(id), "state", state, "error", err)
-		return nil
+		return true, nil
 	}
-	updated, err := result.RowsAffected()
+	updated, err = result.RowsAffected()
 	if err != nil || updated != 1 {
-		return nil
+		return true, nil
 	}
 	if terminal && startedAt.Valid {
 		endAt := now
@@ -327,7 +372,7 @@ func (p *RunProjection) updateState(ctx context.Context, id run.ID, state run.St
 			slog.Warn("step projection duration update unavailable", "runID", string(id), "state", state, "error", durationErr)
 		}
 	}
-	return nil
+	return true, nil
 }
 
 func (p *RunProjection) updateRetry(ctx context.Context, id run.ID, status *run.RetryStatus) error {
@@ -352,12 +397,20 @@ func (p *RunProjection) updateNode(ctx context.Context, id run.ID, state run.Sta
 	}
 	defer tx.Rollback()
 	now := time.Now().UTC()
-	if _, err := tx.ExecContext(ctx, `
+	result, err := tx.ExecContext(ctx, `
 		UPDATE relay_runs SET state = ?, current_node = ?, current_node_visit_id = ?, updated_at = ?
-		WHERE id = ?`,
-		string(state), node, string(visit), now, string(id)); err != nil {
+		WHERE id = ? AND state NOT IN ('canceling', 'completed', 'canceled')`,
+		string(state), node, string(visit), now, string(id))
+	if err != nil {
 		return err
 	}
+	updated, err := result.RowsAffected()
+	if err != nil {
+		return err
+	}
+	if updated != 1 {
+		return tx.Commit()
+	}
 	// A revisit changes only the latest visit ID. Reusable terminal/session
 	// identities remain attached to this run/node row.
 	if _, err := tx.ExecContext(ctx, `
@@ -907,6 +960,18 @@ func (p *RunProjection) UpdateState(ctx context.Context, id run.ID, state run.St
 	return p.updateState(ctx, id, state, lastErr, finished)
 }
 
+// BeginCancellation atomically moves a nonterminal run to canceling and
+// returns the persisted row. Existing canceling rows retain their reason.
+func (p *RunProjection) BeginCancellation(ctx context.Context, id run.ID, reason string) (run.Run, error) {
+	return p.beginCancellation(ctx, id, reason)
+}
+
+// UpdateStateIf applies a lifecycle transition only while the row has the
+// expected state. It returns false when another transition won the race.
+func (p *RunProjection) UpdateStateIf(ctx context.Context, id run.ID, expected, state run.State, lastErr string, finished *time.Time) (bool, error) {
+	return p.updateStateCAS(ctx, id, &expected, state, lastErr, finished)
+}
+
 // UpdateRetry updates or clears active retry metadata.
 func (p *RunProjection) UpdateRetry(ctx context.Context, id run.ID, status *run.RetryStatus) error {
 	return p.updateRetry(ctx, id, status)

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.3.8-alpha"
+const configuredPlugin = "relay-flow-plugin@0.3.9-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.3.8-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.3.9-alpha"
 
 type jsoncToken struct {
 	kind       byte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-flow",
-  "version": "0.3.8-alpha",
+  "version": "0.3.9-alpha",
   "description": "Graph-based agent workflow engine — tracker-agnostic, pluggable runners",
   "bin": {
     "relay-flow": "./bin/relay-flow.js",