relay-flow 0.2.2-alpha → 0.2.4-alpha

package/internal/harness/pi/validation_test.go

@@ -0,0 +1,168 @@
+package pi
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestPiValidateAgentAcceptsDefaultWithPiOnPATH(t *testing.T) {
+	fakeDir := strictPiAvailabilityCLI(t)
+	t.Setenv("PATH", fakeDir)
+
+	h := newPiHarness(t)
+	if err := h.ValidateAgent(context.Background(), "/srv/payments", "default"); err != nil {
+		t.Fatalf("default agent rejected when pi is available: %v", err)
+	}
+}
+
+func TestPiValidateAgentRejectsUnavailablePi(t *testing.T) {
+	directory := t.TempDir()
+	// Keep PATH controlled and empty of both the fake and any host-installed Pi.
+	t.Setenv("PATH", directory)
+
+	h := newPiHarness(t)
+	err := h.ValidateAgent(context.Background(), "/srv/payments", "default")
+	if err == nil {
+		t.Fatal("default agent accepted when pi is unavailable")
+	}
+	if !strings.Contains(err.Error(), "pi") {
+		t.Fatalf("error = %q, want Pi availability context", err)
+	}
+}
+
+func TestPiValidateAgentAcceptsExistingRoleAndPiOnPath(t *testing.T) {
+	fakeDir := strictPiAvailabilityCLI(t)
+	t.Setenv("PATH", fakeDir)
+	repoPath := t.TempDir()
+	rolePath := writePiRole(t, repoPath, "coder", "You are the coder.\n")
+
+	h := newPiHarness(t)
+	if err := h.ValidateAgent(context.Background(), repoPath, "coder"); err != nil {
+		t.Fatalf("existing role %q rejected: %v", rolePath, err)
+	}
+	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
+		t.Fatalf("role validation unexpectedly executed Pi: %v", calls)
+	}
+}
+
+func TestPiValidateAgentRejectsMissingRoleBeforePiLookup(t *testing.T) {
+	fakeDir := strictPiAvailabilityCLI(t)
+	t.Setenv("PATH", fakeDir)
+
+	h := newPiHarness(t)
+	err := h.ValidateAgent(context.Background(), t.TempDir(), "reviewer")
+	if err == nil || !strings.Contains(err.Error(), ".pi/roles/reviewer.md") {
+		t.Fatalf("missing role error = %v, want role path", err)
+	}
+	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
+		t.Fatalf("missing role invoked Pi lookup: %v", calls)
+	}
+}
+
+func TestPiValidateAgentRejectsUnsafeRolePath(t *testing.T) {
+	fakeDir := strictPiAvailabilityCLI(t)
+	t.Setenv("PATH", fakeDir)
+
+	h := newPiHarness(t)
+	for _, role := range []string{"../coder", "subdir/coder", `subdir\\coder`, " ", "."} {
+		if err := h.ValidateAgent(context.Background(), t.TempDir(), role); err == nil {
+			t.Errorf("unsafe role %q accepted", role)
+		}
+	}
+	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
+		t.Fatalf("unsafe roles invoked Pi lookup: %v", calls)
+	}
+}
+
+func TestPiValidateAgentRejectsEmptyAndNonRegularRoleFiles(t *testing.T) {
+	fakeDir := strictPiAvailabilityCLI(t)
+	t.Setenv("PATH", fakeDir)
+
+	emptyRepo := t.TempDir()
+	emptyPath := filepath.Join(emptyRepo, ".pi", "roles", "coder.md")
+	if err := os.MkdirAll(filepath.Dir(emptyPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(emptyPath, nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	directoryRepo := t.TempDir()
+	directoryPath := filepath.Join(directoryRepo, ".pi", "roles", "reviewer.md")
+	if err := os.MkdirAll(directoryPath, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	h := newPiHarness(t)
+	if err := h.ValidateAgent(context.Background(), emptyRepo, "coder"); err == nil || !strings.Contains(err.Error(), "empty") {
+		t.Fatalf("empty role error = %v, want empty-role error", err)
+	}
+	if err := h.ValidateAgent(context.Background(), directoryRepo, "reviewer"); err == nil || !strings.Contains(err.Error(), "regular file") {
+		t.Fatalf("directory role error = %v, want non-regular-role error", err)
+	}
+	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
+		t.Fatalf("invalid role files invoked Pi lookup: %v", calls)
+	}
+}
+
+func TestPiValidateAgentRejectsUnsupportedLabelsWithoutAgentDiscovery(t *testing.T) {
+	fakeDir := strictPiAvailabilityCLI(t)
+	t.Setenv("PATH", fakeDir)
+
+	h := newPiHarness(t)
+	for _, label := range []string{"build", "plan", "gpt-4o", ""} {
+		if err := h.ValidateAgent(context.Background(), "/srv/payments", label); err == nil {
+			t.Errorf("unsupported agent label %q accepted", label)
+		}
+	}
+	if calls := readAvailabilityCalls(t, fakeDir); len(calls) != 0 {
+		t.Fatalf("unsupported labels invoked pi instead of rejecting directly: %v", calls)
+	}
+}
+
+func strictPiAvailabilityCLI(t *testing.T) string {
+	t.Helper()
+	directory := t.TempDir()
+	executable := filepath.Join(directory, "pi")
+	calls := filepath.Join(directory, "calls")
+	script := `#!/bin/sh
+set -eu
+printf '%s\000' "$*" >> "${PI_FAKE_CALLS:?}"
+case "$#:$*" in
+  1:--version) printf '0.84.1\n' ;;
+  *) exit 2 ;;
+esac
+`
+	if err := os.WriteFile(executable, []byte(script), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PI_FAKE_CALLS", calls)
+	return directory
+}
+
+func readAvailabilityCalls(t *testing.T, directory string) []string {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join(directory, "calls"))
+	if os.IsNotExist(err) {
+		return nil
+	}
+	if err != nil {
+		t.Fatal(err)
+	}
+	return strings.Split(strings.TrimSuffix(string(data), "\x00"), "\x00")
+}
+
+func writePiRole(t *testing.T, repoPath, name, content string) string {
+	t.Helper()
+	path := filepath.Join(repoPath, ".pi", "roles", name+".md")
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}

package/internal/identity/identity.go

@@ -6,12 +6,18 @@ import (
 	"crypto/rand"
 	"encoding/hex"
 	"net/url"
+	"strconv"
 	"strings"
 )
 
-// RunID identifies one durable run. Opaque to consumers.
+// RunID identifies one durable execution attempt. Opaque to consumers.
 type RunID string
 
+// AttemptID identifies an execution generation for one logical
+// repo/workflow/ticket run. Attempt numbers are durably allocated by the Run
+// Manager and are intentionally simple numeric values.
+type AttemptID uint64
+
 // NodeVisitID identifies one entry into a workflow node. Opaque to consumers.
 type NodeVisitID string
 
@@ -25,6 +31,27 @@ func NewRunID(repo, workflow, ticket string) RunID {
 	}, "/"))
 }
 
+// NewAttemptRunID derives an execution ID that is fenced from the stable
+// logical run ID. Attempt 1 retains the original deterministic ID for the
+// first execution; explicit restarts use numeric attempt suffixes.
+func NewAttemptRunID(logical RunID, attempt AttemptID) RunID {
+	if attempt <= 1 {
+		return logical
+	}
+	return RunID(string(logical) + "~attempt~" + strconv.FormatUint(uint64(attempt), 10))
+}
+
+// LogicalRunID returns the stable logical ID embedded in an execution ID.
+// First attempts are already logical IDs; explicit attempts use the
+// `~attempt~<number>` suffix generated by NewAttemptRunID.
+func LogicalRunID(execution RunID) RunID {
+	const marker = "~attempt~"
+	if index := strings.LastIndex(string(execution), marker); index >= 0 {
+		return RunID(string(execution)[:index])
+	}
+	return execution
+}
+
 // NewNodeVisitID returns a fresh random node-visit ID. Generation happens
 // once per node entry as a durable replay-safe side effect; this function
 // only produces the random value.

package/internal/identity/identity_test.go

@@ -0,0 +1,40 @@
+package identity_test
+
+import (
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/identity"
+)
+
+func TestAttemptRunIDUsesNumericAttemptSuffix(t *testing.T) {
+	logical := identity.NewRunID("payments", "basicFlow", "PAY-101")
+
+	if got := identity.NewAttemptRunID(logical, 1); got != logical {
+		t.Fatalf("initial attempt ID = %q, want logical ID %q", got, logical)
+	}
+	if got := identity.NewAttemptRunID(logical, 2); got != logical+"~attempt~2" {
+		t.Fatalf("restart attempt ID = %q, want numeric suffix", got)
+	}
+	if got := identity.NewAttemptRunID(logical, 3); got == identity.NewAttemptRunID(logical, 2) {
+		t.Fatalf("attempt IDs are not fenced: attempt 2 and 3 both use %q", got)
+	}
+}
+
+func TestAttemptIDsAreNumeric(t *testing.T) {
+	var first identity.AttemptID = 1
+	var second identity.AttemptID = 2
+	if first != 1 || second != 2 {
+		t.Fatalf("attempt IDs are not numeric: %d, %d", first, second)
+	}
+}
+
+func TestLogicalRunIDStripsAttemptSuffix(t *testing.T) {
+	logical := identity.NewRunID("payments", "basicFlow", "PAY-101")
+	execution := identity.NewAttemptRunID(logical, 4)
+	if got := identity.LogicalRunID(execution); got != logical {
+		t.Fatalf("logical ID = %q, want %q", got, logical)
+	}
+	if got := identity.LogicalRunID(logical); got != logical {
+		t.Fatalf("first-attempt logical ID = %q, want %q", got, logical)
+	}
+}

package/internal/run/manager.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"log/slog"
 	"sync"
+	"time"
 
 	"github.com/rajpopat27/relay-flow/internal/identity"
 	"github.com/rajpopat27/relay-flow/internal/repo"
@@ -13,12 +14,15 @@ import (
 )
 
 // CancellationMarker is the stable parent comment marker recording that the
-// run was canceled; a missing claimed run carrying it is never recreated.
+// logical run was canceled; a missing claimed run carrying it is never
+// recreated by normal polling.
 func CancellationMarker(id ID) string {
 	return string(id) + ":cancellation"
 }
 
-// RunManager performs only assignment and durable-run creation.
+// RunManager performs assignment and durable-run creation. Repos and
+// Workflows are only needed by the explicit restart operation; normal poll
+// handling continues to receive the already-resolved repo/workflow values.
 type RunManager struct {
 	Executor Executor
 	Runs     RunQueries
@@ -28,12 +32,37 @@ type RunManager struct {
 	// a run never starts against a workflow definition that is concurrently
 	// being replaced or removed. A plain *sync.Mutex — no lock service.
 	Gate *sync.Mutex
+
+	// Repos and Workflows resolve the current task-system repo and latest
+	// workflow snapshot for an explicit restart. They are concrete registries,
+	// not task/runner/harness-specific dependencies.
+	Repos     *repo.Registry
+	Workflows *workflow.Registry
+}
+
+func terminalState(state State) bool {
+	return state == StateCompleted || state == StateCanceled
+}
+
+func activeState(state State) bool {
+	return !terminalState(state) && state != StateCanceling
+}
+
+func newerRun(candidate, current Run) bool {
+	if candidate.StartedAt.After(current.StartedAt) {
+		return true
+	}
+	if candidate.StartedAt.Equal(current.StartedAt) && candidate.UpdatedAt.After(current.UpdatedAt) {
+		return true
+	}
+	return false
 }
 
 // EnsureRun claims the ticket if unassigned, skips claiming when the ticket
-// is already assigned to this workflow, checks the stable cancellation
-// marker before recreating a missing claimed run, then ensures the durable
-// run with a value snapshot of the workflow.
+// is already assigned to this workflow, reuses the newest active execution
+// attempt, checks the stable logical cancellation marker before recreating a
+// missing claimed run, then ensures the durable run with a value snapshot of
+// the workflow.
 func (m *RunManager) EnsureRun(ctx context.Context, rp *repo.Repo, wf *workflow.Workflow, ticket task.Ticket) error {
 	if m.Gate != nil {
 		m.Gate.Lock()
@@ -47,19 +76,51 @@ func (m *RunManager) EnsureRun(ctx context.Context, rp *repo.Repo, wf *workflow.
 			break
 		}
 	}
-	existingRun := false
-	if claimed && m.Runs != nil {
-		existing, err := m.Runs.ListRuns(ctx, Filter{Repo: rp.Name, Workflow: wf.Name, Ticket: ticket.Key})
+
+	var candidates []Run
+	if m.Runs != nil {
+		var err error
+		candidates, err = m.Runs.ListRuns(ctx, Filter{Repo: rp.Name, Workflow: wf.Name, Ticket: ticket.Key})
 		if err != nil {
 			return fmt.Errorf("check existing run %s: %w", id, err)
 		}
-		for _, candidate := range existing {
-			if candidate.ID == id {
-				existingRun = true
-				break
-			}
+	}
+	var latest Run
+	latestSet := false
+	var active *Run
+	for _, candidate := range candidates {
+		if candidate.LogicalID == "" {
+			candidate.LogicalID = id
+		}
+		if candidate.AttemptID == 0 {
+			candidate.AttemptID = 1
+		}
+		if !latestSet || newerRun(candidate, latest) {
+			latest = candidate
+			latestSet = true
+		}
+		if activeState(candidate.State) && candidate.ID != "" && (active == nil || newerRun(candidate, *active)) {
+			copy := candidate
+			active = &copy
 		}
 	}
+
+	// A restarted attempt (including a blocked one) is the current execution
+	// and must be ensured by its fenced ID. Do not inspect the cancellation
+	// marker for an active attempt.
+	if active != nil {
+		return m.ensure(ctx, Start{
+			ID: active.ID, LogicalID: active.LogicalID, AttemptID: active.AttemptID,
+			Repo: rp.Name, RepoPath: rp.Path, Workflow: *wf, Ticket: ticket.Ref(),
+		})
+	}
+
+	// Canceling/canceled/completed executions are terminal for normal polling.
+	// Only the explicit restart operation may create a new attempt.
+	if latestSet && (latest.State == StateCanceling || terminalState(latest.State)) {
+		return nil
+	}
+
 	if !claimed {
 		if err := rp.TaskSystem.Claim(ctx, ticket.Ref(), wf.Name); err != nil {
 			slog.Info("ensure-run outcome",
@@ -67,9 +128,9 @@ func (m *RunManager) EnsureRun(ctx context.Context, rp *repo.Repo, wf *workflow.
 				"outcome", "error", "stage", "claim", "error", err)
 			return fmt.Errorf("claim %s for workflow %s: %w", ticket.Key, wf.Name, err)
 		}
-	} else if !existingRun {
-		// Claimed but possibly missing its run (claim-before-run crash gap or
-		// retention cleanup): never recreate a canceled run.
+	} else {
+		// Claimed but missing its run (claim-before-run crash gap or retention
+		// cleanup): never recreate a canceled logical run.
 		marked, err := rp.TaskSystem.HasComment(ctx, task.Target{Parent: ticket.Ref()}, CancellationMarker(id))
 		if err != nil {
 			slog.Info("ensure-run outcome",
@@ -84,29 +145,136 @@ func (m *RunManager) EnsureRun(ctx context.Context, rp *repo.Repo, wf *workflow.
 			return nil
 		}
 	}
-	created, err := m.Executor.EnsureRun(ctx, Start{
-		ID:       id,
-		Repo:     rp.Name,
-		RepoPath: rp.Path,
-		Workflow: *wf,
-		Ticket:   ticket.Ref(),
+	return m.ensure(ctx, Start{
+		ID: id, LogicalID: id, AttemptID: 1,
+		Repo: rp.Name, RepoPath: rp.Path, Workflow: *wf, Ticket: ticket.Ref(),
 	})
+}
+
+func (m *RunManager) ensure(ctx context.Context, start Start) error {
+	if m.Executor == nil {
+		return fmt.Errorf("ensure run %s: executor is not configured", start.ID)
+	}
+	created, err := m.Executor.EnsureRun(ctx, start)
 	if err != nil {
 		slog.Info("ensure-run outcome",
-			"ticket", ticket.Key, "repo", rp.Name, "workflow", wf.Name, "runID", string(id),
+			"ticket", start.Ticket.Key, "repo", start.Repo, "workflow", start.Workflow.Name, "runID", string(start.ID),
 			"outcome", "error", "stage", "executor", "error", err)
-		return fmt.Errorf("ensure run %s: %w", id, err)
+		return fmt.Errorf("ensure run %s: %w", start.ID, err)
 	}
 	outcome := "exists"
 	if created {
 		outcome = "created"
 	}
 	slog.Info("ensure-run outcome",
-		"ticket", ticket.Key, "repo", rp.Name, "workflow", wf.Name, "runID", string(id),
+		"ticket", start.Ticket.Key, "repo", start.Repo, "workflow", start.Workflow.Name, "runID", string(start.ID),
 		"outcome", outcome)
 	return nil
 }
 
+// RestartByTicket creates or returns the one active fresh attempt for a
+// canceled ticket. It resolves the repo and latest workflow from the current
+// registries, so the new durable snapshot is never copied from the canceled
+// attempt. External task/runner/harness behavior remains behind their normal
+// boundaries and is performed by the durable workflow after creation.
+func (m *RunManager) RestartByTicket(ctx context.Context, ticket string) (Run, error) {
+	if m.Gate != nil {
+		m.Gate.Lock()
+		defer m.Gate.Unlock()
+	}
+	if m.Runs == nil {
+		return Run{}, fmt.Errorf("restart %s: run queries are not configured", ticket)
+	}
+	previous, err := m.Runs.FindRunByTicket(ctx, ticket)
+	if err != nil {
+		return Run{}, fmt.Errorf("find run for ticket %s: %w", ticket, err)
+	}
+
+	// Repeating the command while the fresh attempt is active is idempotent.
+	// A canceling attempt is deliberately not treated as active: callers must
+	// wait for cancellation cleanup to finish before starting another attempt.
+	if activeState(previous.State) && previous.AttemptID != 0 {
+		return previous, nil
+	}
+	if previous.State == StateCanceling {
+		return Run{}, fmt.Errorf("%w: run %s is still canceling; wait for cancellation to finish", ErrRestartConflict, previous.ID)
+	}
+	if previous.State != StateCanceled {
+		return Run{}, fmt.Errorf("%w: run %s is %s; only canceled runs can be restarted", ErrRestartConflict, previous.ID, previous.State)
+	}
+	if m.Executor == nil || m.Repos == nil || m.Workflows == nil {
+		return Run{}, fmt.Errorf("restart %s: restart dependencies are not configured", ticket)
+	}
+
+	rp, ok := m.Repos.Get(previous.Repo)
+	if !ok {
+		return Run{}, fmt.Errorf("%w: repo %q for canceled run %s is no longer registered", ErrRestartConflict, previous.Repo, previous.ID)
+	}
+	wf, ok := m.Workflows.Get(previous.Workflow)
+	if !ok {
+		return Run{}, fmt.Errorf("%w: workflow %q for canceled run %s is no longer stored", ErrRestartConflict, previous.Workflow, previous.ID)
+	}
+	bound := false
+	for _, name := range wf.Repos {
+		if name == previous.Repo {
+			bound = true
+			break
+		}
+	}
+	if !bound {
+		return Run{}, fmt.Errorf("%w: workflow %q no longer targets repo %q", ErrRestartConflict, wf.Name, previous.Repo)
+	}
+
+	logicalID := previous.LogicalID
+	if logicalID == "" {
+		logicalID = identity.NewRunID(previous.Repo, previous.Workflow, previous.Ticket.Key)
+	}
+	// The lifecycle gate makes max+1 allocation single-writer within the
+	// server. Because every prior attempt is persisted in relay_runs, the
+	// number remains stable across process restarts and repeated commands.
+	attempts, err := m.Runs.ListRuns(ctx, Filter{Repo: previous.Repo, Workflow: previous.Workflow, Ticket: ticket})
+	if err != nil {
+		return Run{}, fmt.Errorf("allocate restart attempt for %s: %w", ticket, err)
+	}
+	var attemptID AttemptID = 1
+	for _, candidate := range attempts {
+		candidateAttempt := candidate.AttemptID
+		if candidateAttempt == 0 {
+			candidateAttempt = 1
+		}
+		if candidateAttempt >= attemptID {
+			if candidateAttempt == ^AttemptID(0) {
+				return Run{}, fmt.Errorf("%w: attempt number exhausted for %s", ErrRestartConflict, ticket)
+			}
+			attemptID = candidateAttempt + 1
+		}
+	}
+	executionID := identity.NewAttemptRunID(logicalID, attemptID)
+	start := Start{
+		ID: executionID, LogicalID: logicalID, AttemptID: attemptID,
+		Repo: previous.Repo, RepoPath: rp.Path, Workflow: *wf, Ticket: previous.Ticket,
+	}
+	if start.Ticket.Key == "" {
+		start.Ticket.Key = ticket
+	}
+	if err := m.ensure(ctx, start); err != nil {
+		return Run{}, err
+	}
+
+	// The real projection is inserted before the durable instance is started.
+	// A fake or an engine that cannot read it yet still gets a useful command
+	// result; a later poll/EnsureRun repairs a missing workflow instance.
+	if current, err := m.Runs.GetRun(ctx, executionID); err == nil {
+		return current, nil
+	}
+	now := time.Now().UTC()
+	return Run{
+		ID: executionID, LogicalID: logicalID, AttemptID: attemptID,
+		Repo: start.Repo, Workflow: start.Workflow.Name, Ticket: start.Ticket,
+		State: StateStarting, StartedAt: now, UpdatedAt: now,
+	}, nil
+}
+
 // CancelByTicket resolves the active run through FindRunByTicket, then
 // calls Executor.CancelRun.
 func (m *RunManager) CancelByTicket(ctx context.Context, ticket, reason string) error {

package/internal/run/run.go

@@ -4,6 +4,7 @@ package run
 
 import (
 	"context"
+	"errors"
 	"time"
 
 	"github.com/rajpopat27/relay-flow/internal/config"
@@ -13,6 +14,7 @@ import (
 )
 
 type ID = identity.RunID
+type AttemptID = identity.AttemptID
 type NodeVisitID = identity.NodeVisitID
 
 type State string
@@ -30,12 +32,20 @@ const (
 // Start carries the immutable value snapshot of the accepted workflow for
 // deterministic replay. The interpreter consumes only this snapshot.
 type Start struct {
-	ID       ID                `json:"id"`
-	Repo     string            `json:"repo"`
-	RepoPath string            `json:"repoPath"`
-	Workflow workflow.Workflow `json:"workflow"`
-	Ticket   task.TicketRef    `json:"ticket"`
-	Runtime  RuntimePolicy     `json:"runtime"`
+	// ID is the durable execution-attempt ID. The first attempt (attempt 1)
+	// uses the deterministic logical ID; explicit restarts use a fenced ID.
+	ID ID `json:"id"`
+	// LogicalID remains stable across explicit attempts and is used for
+	// task-system cancellation fencing and ticket lookup.
+	LogicalID ID `json:"logicalRunId,omitempty"`
+	// AttemptID is 1 for the original execution and increases for explicit
+	// restarts. Zero is accepted only for legacy callers and normalized to 1.
+	AttemptID AttemptID         `json:"attemptId,omitempty"`
+	Repo      string            `json:"repo"`
+	RepoPath  string            `json:"repoPath"`
+	Workflow  workflow.Workflow `json:"workflow"`
+	Ticket    task.TicketRef    `json:"ticket"`
+	Runtime   RuntimePolicy     `json:"runtime"`
 }
 
 type RuntimePolicy struct {
@@ -45,6 +55,8 @@ type RuntimePolicy struct {
 
 type Work struct {
 	RunID              ID
+	LogicalID          ID
+	AttemptID          AttemptID
 	Repo               string
 	Workflow           string
 	Parent             task.TicketRef
@@ -81,6 +93,8 @@ type RetryStatus struct {
 
 type Run struct {
 	ID                 ID             `json:"id"`
+	LogicalID          ID             `json:"logicalRunId,omitempty"`
+	AttemptID          AttemptID      `json:"attemptId,omitempty"`
 	Repo               string         `json:"repo"`
 	Workflow           string         `json:"workflow"`
 	Ticket             task.TicketRef `json:"ticket"`
@@ -106,6 +120,10 @@ type ReportAck struct {
 	Duplicate bool `json:"duplicate"`
 }
 
+// ErrRestartConflict means the ticket cannot accept an explicit restart in
+// its current durable state. Server handlers map it to HTTP 409.
+var ErrRestartConflict = errors.New("restart conflict")
+
 // NodeRuntimeRegistration binds the OpenCode session emitted for one run/node.
 type NodeRuntimeRegistration struct {
 	RunID     ID     `json:"runId"`