relay-flow 0.2.2-alpha → 0.2.4-alpha

package/examples/workflow-reference.yaml

@@ -0,0 +1,111 @@
+# Complete workflow definition reference.
+#
+# This example uses Jira-native values and the OpenCode agent names build and
+# plan. For Beads, use provider-native values: open, task, in_progress, and
+# closed. For Pi, use default or a repository role from .pi/roles/<agent>.md.
+
+name: referenceFlow
+
+repos:
+  - payments
+
+cleanupRunnerOnEnd: true
+
+taskConfig:
+  # Optional assignee inherited by node mailboxes. It does not filter parent
+  # tickets; use filters.assignees for ticket pickup.
+  assignee: developer@example.com
+
+  filters:
+    parentStatuses:
+      - To Do
+    issueTypes:
+      - Task
+    labels:
+      - relay-ready
+    assignees:
+      - currentUser()
+      # Jira-only symbolic value: resolves to the authenticated Jira email.
+      # Other assignee values are normalized Jira emails, not JQL expressions.
+
+  # filters.assignees controls ticket pickup independently of assignee.
+  # Use an explicit empty list to include all assignees while retaining any
+  # inherited mailbox assignment:
+  # filters:
+  #   assignees: []
+  # To disable mailbox assignment too, set assignee: "" at this scope.
+
+  # Prefer lifecycle-specific transitionTo values on start, work nodes, and
+  # end. A value here is inherited by every lifecycle point that reads it.
+  # transitionTo:
+  #   parentStatus: In Progress
+  #   taskStatus: In Progress
+
+nodes:
+  start:
+    # start has no type, agent, description, nudgePrompt, or failure routes.
+    taskConfig:
+      transitionTo:
+        parentStatus: In Progress
+    onSuccess:
+      - target: implement
+        when: The parent ticket is ready for implementation.
+
+  implement:
+    type: agent
+    agent: build
+    description: |
+      Implement the parent ticket in the ticket worktree.
+      Run the relevant tests and verification commands.
+    nudgePrompt: |
+      Continue working on {{ticket}} at node {{node}}.
+      Read the latest mailbox feedback.
+      Valid next steps are: {{nextSteps}}.
+      Return the complete report contract.
+    taskConfig:
+      transitionTo:
+        taskStatus: In Progress
+    onSuccess:
+      - target: review
+        when: Implementation and verification are complete.
+    onFailure:
+      - target: implement
+        when: Implementation needs another pass.
+
+  review:
+    type: agent
+    agent: plan
+    description: |
+      Review the implementation for correctness, regressions, missing tests,
+      and unresolved issues. Prepare the work for human PR review.
+    taskConfig:
+      transitionTo:
+        taskStatus: In Progress
+    onSuccess:
+      - target: prReview
+        when: The implementation is ready for human PR review.
+    onFailure:
+      - target: implement
+        when: The review found issues requiring implementation changes.
+
+  prReview:
+    type: hitl
+    agent: plan
+    description: |
+      Review the implementation and proposed changes with a human.
+      Approve the work or request implementation changes.
+    taskConfig:
+      transitionTo:
+        taskStatus: In Progress
+    onSuccess:
+      - target: end
+        when: The human approves the PR review.
+    onFailure:
+      - target: implement
+        when: The human requests changes.
+
+  end:
+    # end has no type, agent, description, nudgePrompt, or routes.
+    taskConfig:
+      transitionTo:
+        parentStatus: Done

package/internal/execution/goworkflows/activities.go

@@ -64,6 +64,25 @@ func (a *Activities) EnsureMailboxes(ctx context.Context, w run.Work, specs []ta
 	return sys.EnsureMailboxes(ctx, w.Parent, w.Workflow, specs)
 }
 
+// PrepareRestart reopens mailbox state through the optional task-system
+// capability, then closes any surviving run-owned terminals while preserving
+// the ticket worktree. Both operations are idempotent/retryable and remain
+// behind their respective task and runner interfaces.
+func (a *Activities) PrepareRestart(ctx context.Context, w run.Work, repoPath string, mailboxes []task.Mailbox) error {
+	sys, err := a.taskSystem(w.Repo)
+	if err != nil {
+		return err
+	}
+	if preparer, ok := sys.(task.RestartPreparer); ok {
+		if err := preparer.PrepareRestart(ctx, w.Parent, mailboxes); err != nil {
+			return err
+		}
+	}
+	spec := a.runSpec(w)
+	spec.RepoPath = repoPath
+	return a.Runner.CloseTerminals(ctx, spec)
+}
+
 // ValidateAgents validates every referenced agent on the repo.
 func (a *Activities) ValidateAgents(ctx context.Context, repoPath string, agents []string) error {
 	for _, agent := range agents {

package/internal/execution/goworkflows/engine.go

@@ -24,6 +24,7 @@ import (
 	"github.com/google/uuid"
 
 	"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/run"
 	"github.com/rajpopat27/relay-flow/internal/runner"
@@ -220,6 +221,7 @@ func (e *Engine) registerActivities() error {
 	a := e.activities
 	for _, act := range []goworkflow.Activity{
 		a.EnsureMailboxes,
+		a.PrepareRestart,
 		a.ValidateAgents,
 		a.ApplyTaskConfig,
 		a.EnsureEnvironment,
@@ -283,6 +285,12 @@ func (e *Engine) Shutdown(ctx context.Context) error {
 // title and sends the reconcile signal only when that terminal is missing
 // or unusable. Repeated polls are harmless.
 func (e *Engine) EnsureRun(ctx context.Context, start run.Start) (bool, error) {
+	if start.LogicalID == "" {
+		start.LogicalID = run.ID(identity.LogicalRunID(start.ID))
+	}
+	if start.AttemptID == 0 {
+		start.AttemptID = 1
+	}
 	r, err := e.runs.get(ctx, start.ID)
 	if errors.Is(err, errRunNotFound) {
 		start.Runtime = e.runtime
@@ -358,6 +366,18 @@ func (e *Engine) EnsureRun(ctx context.Context, start run.Start) (bool, error) {
 // Attrs always carry ticket/runID/node/nodeVisitID when known.
 func (e *Engine) SubmitReport(ctx context.Context, req run.ReportRequest) (run.ReportAck, error) {
 	r, err := e.runs.get(ctx, req.RunID)
+	if errors.Is(err, errRunNotFound) {
+		// A retained newer attempt can outlive an old attempt row. Resolve the
+		// stable logical ID and acknowledge the old attempt as a stale
+		// duplicate; it must never be validated or signaled into the new run.
+		logicalID := run.ID(identity.LogicalRunID(req.RunID))
+		if latest, lookupErr := e.runs.findByLogicalID(ctx, logicalID); lookupErr == nil && latest.ID != req.RunID {
+			slog.Info("report duplicate ack", "ticket", latest.Ticket.Key,
+				"runID", string(req.RunID), "logicalRunID", string(logicalID),
+				"node", req.Node, "reportID", req.ReportID, "state", string(latest.State))
+			return run.ReportAck{Accepted: true, Duplicate: true}, nil
+		}
+	}
 	if err != nil {
 		return run.ReportAck{}, fmt.Errorf("resolve run %s: %w", req.RunID, err)
 	}

package/internal/execution/goworkflows/engine_test.go

@@ -71,7 +71,7 @@ func TestMailboxDescriptionAndLaunchPromptAreTaskSystemNeutral(t *testing.T) {
 		if err != nil {
 			t.Fatal(err)
 		}
-		want := "Task system: " + taskSystem + "\nUse the " + taskSystem + " tools to read the parent ticket PAY-101.\n\nYour mailbox is PAY-234. Read its description and comments for node instructions and feedback.\n\nBefore submitting your report, present the complete proposed report through OpenCode's built-in Question tool with exactly two options: Approve and Reject. Submit it only after an explicit Approve answer."
+		want := "Task system: " + taskSystem + "\nUse the " + taskSystem + " tools to read the parent ticket PAY-101.\n\nYour mailbox is PAY-234. Read its description and comments for node instructions and feedback.\n\nReturn the complete report directly. Relay-flow will show a native TUI approval dialog after the report is valid. Do not use OpenCode's Question tool for relay-flow approval."
 		if prompt != want {
 			t.Fatalf("RenderPrompt(%s) = %q, want %q", taskSystem, prompt, want)
 		}

package/internal/execution/goworkflows/fakes_test.go

@@ -82,6 +82,7 @@ type fakeTaskSystem struct {
 	completeFail     int           // next N CompleteMailbox calls return transient error
 	completeConflict bool          // CompleteMailbox returns retry.ConflictError
 	completeSlow     time.Duration // CompleteMailbox sleeps (a running activity)
+	startConflict    bool          // start ApplyTaskConfig returns a status conflict
 	failComments     bool          // Comment returns transient error
 
 	// Recovery fixtures.
@@ -165,6 +166,15 @@ func (s *fakeTaskSystem) EnsureMailboxes(_ context.Context, parent task.TicketRe
 
 func (s *fakeTaskSystem) ApplyTaskConfig(_ context.Context, target task.Target, cfg config.RawValues) error {
 	key := target.Parent.Key
+	if target.Mailbox == nil {
+		s.mu.Lock()
+		conflict := s.startConflict
+		s.mu.Unlock()
+		if conflict {
+			s.log.add("applyTaskConfigConflict:" + key)
+			return retry.ConflictError(errStartConflict)
+		}
+	}
 	if target.Mailbox != nil {
 		key = target.Mailbox.Key
 		s.mu.Lock()
@@ -227,6 +237,16 @@ func (s *fakeTaskSystem) Comment(_ context.Context, target task.Target, body, ma
 	return nil
 }
 
+func (s *fakeTaskSystem) PrepareRestart(_ context.Context, parent task.TicketRef, mbs []task.Mailbox) error {
+	s.mu.Lock()
+	for _, mb := range mbs {
+		s.mailboxStatus[mb.Key] = "To Do"
+	}
+	s.mu.Unlock()
+	s.log.add("prepareRestart:" + parent.Key)
+	return nil
+}
+
 func (s *fakeTaskSystem) ResetForRecovery(_ context.Context, parent task.TicketRef, mbs []task.Mailbox, _ config.RawValues) error {
 	s.mu.Lock()
 	for _, mb := range mbs {
@@ -287,6 +307,12 @@ func (s *fakeTaskSystem) setMailboxStatus(key, status string) {
 	s.mu.Unlock()
 }
 
+func (s *fakeTaskSystem) setStartConflict(value bool) {
+	s.mu.Lock()
+	s.startConflict = value
+	s.mu.Unlock()
+}
+
 // seedMailbox pre-populates an existing mailbox (with labels) for recovery
 // and reuse tests.
 func (s *fakeTaskSystem) seedMailbox(parentKey string, mb task.Mailbox, labels []string) {
@@ -345,11 +371,12 @@ func (f *fakeRunner) ValidateRepo(context.Context, string, string) error { retur
 func (f *fakeRunner) EnsureEnvironment(_ context.Context, spec runner.RunSpec) (runner.Environment, error) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
-	if e, ok := f.envs[string(spec.RunID)]; ok {
+	key := spec.TicketKey
+	if e, ok := f.envs[key]; ok {
 		return e, nil
 	}
-	e := runner.Environment{ID: "env-" + string(spec.RunID), Path: spec.RepoPath}
-	f.envs[string(spec.RunID)] = e
+	e := runner.Environment{ID: "env-" + spec.TicketKey, Path: spec.RepoPath}
+	f.envs[key] = e
 	f.log.add("ensureEnvironment:" + string(spec.RunID))
 	return e, nil
 }
@@ -418,7 +445,7 @@ func (f *fakeRunner) CloseTerminal(_ context.Context, t runner.Terminal) error {
 func (f *fakeRunner) CloseTerminals(_ context.Context, spec runner.RunSpec) error {
 	f.mu.Lock()
 	defer f.mu.Unlock()
-	prefix := "env-" + string(spec.RunID) + "/"
+	prefix := "env-" + spec.TicketKey + "/"
 	for k, ft := range f.terminals {
 		if len(k) >= len(prefix) && k[:len(prefix)] == prefix {
 			ft.live = false
@@ -433,13 +460,13 @@ func (f *fakeRunner) CloseTerminals(_ context.Context, spec runner.RunSpec) erro
 func (f *fakeRunner) CleanupRun(_ context.Context, spec runner.RunSpec) error {
 	f.mu.Lock()
 	defer f.mu.Unlock()
-	prefix := "env-" + string(spec.RunID) + "/"
+	prefix := "env-" + spec.TicketKey + "/"
 	for k := range f.terminals {
 		if len(k) >= len(prefix) && k[:len(prefix)] == prefix {
 			delete(f.terminals, k)
 		}
 	}
-	delete(f.envs, string(spec.RunID))
+	delete(f.envs, spec.TicketKey)
 	f.cleaned = append(f.cleaned, string(spec.RunID))
 	f.log.add("cleanupRun:" + string(spec.RunID))
 	return nil
@@ -553,3 +580,4 @@ type conflictError struct{ msg string }
 func (e *conflictError) Error() string { return e.msg }
 
 var errConflict = &conflictError{msg: "human moved mailbox"}
+var errStartConflict = &conflictError{msg: "human moved ticket status"}

package/internal/execution/goworkflows/interpreter.go

@@ -57,10 +57,18 @@ func jitter(ctx goworkflow.Context) (float64, error) {
 // deterministic. On cancellation it runs cancellation cleanup on a
 // disconnected context.
 func (a *Activities) TicketWorkflow(ctx goworkflow.Context, start run.Start) error {
+	if start.LogicalID == "" {
+		start.LogicalID = run.ID(identity.LogicalRunID(start.ID))
+	}
+	if start.AttemptID == 0 {
+		start.AttemptID = 1
+	}
 	err := a.runGraph(ctx, start)
 	if err != nil && ctx.Err() != nil {
 		work := run.Work{
 			RunID:              start.ID,
+			LogicalID:          start.LogicalID,
+			AttemptID:          start.AttemptID,
 			Repo:               start.Repo,
 			Workflow:           start.Workflow.Name,
 			Parent:             start.Ticket,
@@ -76,6 +84,8 @@ func (a *Activities) runGraph(ctx goworkflow.Context, start run.Start) error {
 	wf := start.Workflow // value snapshot
 	work := run.Work{
 		RunID:              start.ID,
+		LogicalID:          start.LogicalID,
+		AttemptID:          start.AttemptID,
 		Repo:               start.Repo,
 		Workflow:           wf.Name,
 		Parent:             start.Ticket,
@@ -93,6 +103,26 @@ func (a *Activities) runGraph(ctx goworkflow.Context, start run.Start) error {
 		return err
 	}
 
+	// An explicit restart reuses the task-system mailboxes and ticket
+	// worktree, but resets relay-owned mailbox state and closes stale node
+	// terminals before the fresh start edge is processed. Human-owned
+	// incompatible states are returned as conflicts and keep this attempt
+	// blocked until the human restores a compatible state.
+	if start.AttemptID > 1 {
+		mailboxList := make([]task.Mailbox, 0, len(mailboxes))
+		for _, mailbox := range mailboxes {
+			mailboxList = append(mailboxList, mailbox)
+		}
+		sort.Slice(mailboxList, func(i, j int) bool { return mailboxList[i].Node < mailboxList[j].Node })
+		if _, err := retryLoop(ctx, start.ID, a, work, "start",
+			func(ctx2 goworkflow.Context) goworkflow.Future[struct{}] {
+				return goworkflow.ExecuteActivity[struct{}](ctx2, noNativeRetries,
+					a.PrepareRestart, work, start.RepoPath, mailboxList)
+			}); err != nil {
+			return err
+		}
+	}
+
 	// Validate every referenced agent before the start edge.
 	agentSet := map[string]bool{}
 	for _, n := range wf.Nodes {
@@ -443,6 +473,7 @@ func retryLoop[T any](ctx goworkflow.Context, id run.ID, a *Activities, work run
 		}
 		f := classifyActivityError(err)
 		if f.Kind == retry.Conflict {
+			f.Message = blockedMessage(work, node, f.Message)
 			// Mark blocked, keep retrying on the capped schedule.
 			_, _ = scheduleState(ctx, a, id, run.StateBlocked, f.Message)
 			blocked = true
@@ -463,6 +494,18 @@ func retryLoop[T any](ctx goworkflow.Context, id run.ID, a *Activities, work run
 	}
 }
 
+func blockedMessage(work run.Work, node, message string) string {
+	message = strings.TrimRight(message, ". ")
+	lower := strings.ToLower(message)
+	if node == "start" && !strings.Contains(lower, "mailbox") {
+		return fmt.Sprintf("%s. Move ticket %s to an allowed active start status; relay-flow will retry automatically", message, work.Parent.Key)
+	}
+	if node != "" {
+		return fmt.Sprintf("%s. Restore the task-system state required for node %s; relay-flow will retry automatically", message, node)
+	}
+	return fmt.Sprintf("%s. Restore the task-system state required by this operation; relay-flow will retry automatically", message)
+}
+
 // logRetry emits the 9.6 retry-classification info line, replay-safe.
 // Attrs come from the always-known run.Work value carried by the caller,
 // so ticket/repo/workflow are present even if the projection is briefly
@@ -565,6 +608,10 @@ func mustJitter(ctx goworkflow.Context) float64 {
 // canceled. No rollback/compensation ever runs.
 func (a *Activities) cancelCleanup(ctx goworkflow.Context, work run.Work, repoPath, reason string) error {
 	dctx := goworkflow.NewDisconnectedContext(ctx)
+	markerID := work.LogicalID
+	if markerID == "" {
+		markerID = work.RunID
+	}
 	if _, err := retryLoop(dctx, work.RunID, a, work, "",
 		func(ctx2 goworkflow.Context) goworkflow.Future[struct{}] {
 			return goworkflow.ExecuteActivity[struct{}](ctx2, noNativeRetries,
@@ -578,7 +625,7 @@ func (a *Activities) cancelCleanup(ctx goworkflow.Context, work run.Work, repoPa
 				RunID:  work.RunID,
 				Item:   task.Target{Parent: work.Parent},
 				Body:   "Run canceled: " + reason,
-				Marker: run.CancellationMarker(work.RunID),
+				Marker: run.CancellationMarker(markerID),
 			})
 		}); err != nil {
 		return err

package/internal/execution/goworkflows/projection.go

@@ -34,6 +34,8 @@ type NodeRuntime struct {
 const relayRunsSchema = `
 CREATE TABLE IF NOT EXISTS relay_runs (
     id TEXT PRIMARY KEY,
+    logical_run_id TEXT,
+    attempt_id INTEGER,
     repo TEXT NOT NULL,
     workflow TEXT NOT NULL,
     ticket_id TEXT NOT NULL,
@@ -86,9 +88,11 @@ func (p *RunProjection) migrate() error {
 		return err
 	}
 	for name, definition := range map[string]string{
-		"retry_error":   "TEXT",
-		"retry_attempt": "INTEGER",
-		"next_retry_at": "DATETIME",
+		"logical_run_id": "TEXT",
+		"attempt_id":     "INTEGER",
+		"retry_error":    "TEXT",
+		"retry_attempt":  "INTEGER",
+		"next_retry_at":  "DATETIME",
 	} {
 		var count int
 		if err := p.DB.QueryRow(`SELECT COUNT(1) FROM pragma_table_info('relay_runs') WHERE name = ?`, name).Scan(&count); err != nil {
@@ -100,6 +104,15 @@ func (p *RunProjection) migrate() error {
 			}
 		}
 	}
+	// Rows created before attempt identities were introduced represent the
+	// original attempt. Backfill the stable logical ID and attempt number so
+	// restart allocation remains numeric and never reuses attempt 1.
+	if _, err := p.DB.Exec(`UPDATE relay_runs SET logical_run_id = id WHERE COALESCE(logical_run_id, '') = ''`); err != nil {
+		return err
+	}
+	if _, err := p.DB.Exec(`UPDATE relay_runs SET attempt_id = 1 WHERE attempt_id IS NULL OR attempt_id = 0`); err != nil {
+		return err
+	}
 	return nil
 }
 
@@ -110,11 +123,19 @@ var errNodeRuntimeNotFound = errors.New("node runtime not found")
 func IsNotFound(err error) bool { return errors.Is(err, errRunNotFound) }
 
 func (p *RunProjection) insertStart(ctx context.Context, s run.Start, now time.Time) error {
+	logicalID := s.LogicalID
+	if logicalID == "" {
+		logicalID = s.ID
+	}
+	attemptID := s.AttemptID
+	if attemptID == 0 {
+		attemptID = 1
+	}
 	_, err := p.DB.ExecContext(ctx, `
-		INSERT INTO relay_runs (id, repo, workflow, ticket_id, ticket_key, state, started_at, updated_at)
-		VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+		INSERT INTO relay_runs (id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, started_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 		ON CONFLICT(id) DO NOTHING`,
-		string(s.ID), s.Repo, s.Workflow.Name, s.Ticket.ID, s.Ticket.Key,
+		string(s.ID), string(logicalID), int64(attemptID), s.Repo, s.Workflow.Name, s.Ticket.ID, s.Ticket.Key,
 		string(run.StateStarting), now, now)
 	return err
 }
@@ -360,7 +381,7 @@ func nullableString(value string) any {
 
 func (p *RunProjection) get(ctx context.Context, id run.ID) (run.Run, error) {
 	row := p.DB.QueryRowContext(ctx, `
-		SELECT id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
+		SELECT id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
 			retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at
 		FROM relay_runs WHERE id = ?`, string(id))
 	return scanRun(row)
@@ -368,9 +389,17 @@ func (p *RunProjection) get(ctx context.Context, id run.ID) (run.Run, error) {
 
 func (p *RunProjection) findByTicket(ctx context.Context, ticket string) (run.Run, error) {
 	row := p.DB.QueryRowContext(ctx, `
-		SELECT id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
+		SELECT id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
 			retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at
-		FROM relay_runs WHERE ticket_key = ? ORDER BY started_at DESC LIMIT 1`, ticket)
+		FROM relay_runs WHERE ticket_key = ? ORDER BY started_at DESC, attempt_id DESC LIMIT 1`, ticket)
+	return scanRun(row)
+}
+
+func (p *RunProjection) findByLogicalID(ctx context.Context, logicalID run.ID) (run.Run, error) {
+	row := p.DB.QueryRowContext(ctx, `
+		SELECT id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error,
+			retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at
+		FROM relay_runs WHERE logical_run_id = ? ORDER BY started_at DESC, attempt_id DESC LIMIT 1`, string(logicalID))
 	return scanRun(row)
 }
 
@@ -380,11 +409,13 @@ type rowScanner interface {
 
 func scanRun(row rowScanner) (run.Run, error) {
 	var r run.Run
+	var logicalID sql.NullString
+	var attemptNumber sql.NullInt64
 	var node, visit, lastErr, retryErr sql.NullString
 	var retryAttempt sql.NullInt64
 	var nextRetry, finished sql.NullTime
 	var started, updated time.Time
-	err := row.Scan(&r.ID, &r.Repo, &r.Workflow, &r.Ticket.ID, &r.Ticket.Key, &r.State,
+	err := row.Scan(&r.ID, &logicalID, &attemptNumber, &r.Repo, &r.Workflow, &r.Ticket.ID, &r.Ticket.Key, &r.State,
 		&node, &visit, &lastErr, &retryErr, &retryAttempt, &nextRetry, &started, &updated, &finished)
 	if errors.Is(err, sql.ErrNoRows) {
 		return run.Run{}, errRunNotFound
@@ -392,6 +423,16 @@ func scanRun(row rowScanner) (run.Run, error) {
 	if err != nil {
 		return run.Run{}, err
 	}
+	if logicalID.Valid && logicalID.String != "" {
+		r.LogicalID = run.ID(logicalID.String)
+	} else {
+		r.LogicalID = r.ID
+	}
+	if attemptNumber.Valid && attemptNumber.Int64 > 0 {
+		r.AttemptID = run.AttemptID(attemptNumber.Int64)
+	} else {
+		r.AttemptID = 1
+	}
 	r.CurrentNode = node.String
 	r.CurrentNodeVisitID = run.NodeVisitID(visit.String)
 	r.LastError = lastErr.String
@@ -410,7 +451,7 @@ func scanRun(row rowScanner) (run.Run, error) {
 }
 
 func (p *RunProjection) list(ctx context.Context, f run.Filter) ([]run.Run, error) {
-	q := `SELECT id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error, retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at FROM relay_runs WHERE 1=1`
+	q := `SELECT id, logical_run_id, attempt_id, repo, workflow, ticket_id, ticket_key, state, current_node, current_node_visit_id, last_error, retry_error, retry_attempt, next_retry_at, started_at, updated_at, finished_at FROM relay_runs WHERE 1=1`
 	var args []any
 	if f.Repo != "" {
 		q += ` AND repo = ?`

package/internal/execution/goworkflows/recovery_test.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -219,6 +220,131 @@ func TestCancelRun(t *testing.T) {
 	}
 }
 
+func TestExplicitRestartCreatesFreshAttemptFromStart(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	fh := newFakeHarness(log)
+	repos := repoRegistryWith("payments", sys)
+	wf := linearWorkflow(false)
+	workflows := &workflow.Registry{}
+	workflows.Replace(&wf)
+	engine := newEngine(t, goworkflows.Dependencies{
+		Repos: repos, Runner: fr, Harness: fh,
+	})
+	oldID, err := startRun(engine, wf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), oldID)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+	if err := engine.CancelRun(context.Background(), oldID, "operator requested restart"); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), oldID)
+		return r.State == run.StateCanceled
+	})
+
+	manager := &run.RunManager{
+		Executor: engine, Runs: engine, Repos: repos, Workflows: workflows,
+	}
+	fresh, err := manager.RestartByTicket(context.Background(), "PAY-101")
+	if err != nil {
+		t.Fatalf("RestartByTicket failed: %v", err)
+	}
+	if fresh.ID == oldID || fresh.LogicalID != oldID || fresh.AttemptID != 2 {
+		t.Fatalf("fresh attempt = %+v, want logical=%q attempt=2 and a new ID", fresh, oldID)
+	}
+	oldAck, err := engine.SubmitReport(context.Background(), reportRequest(oldID, "coding", successReport("end")))
+	if err != nil || !oldAck.Accepted || !oldAck.Duplicate {
+		t.Fatalf("stale old-attempt report ack=%+v err=%v, want accepted duplicate", oldAck, err)
+	}
+	if got := string(fresh.ID); got != string(oldID)+"~attempt~2" {
+		t.Fatalf("fresh execution ID = %q, want numeric attempt suffix", got)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), fresh.ID)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+
+	current, err := engine.GetRun(context.Background(), fresh.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	latest, err := engine.FindRunByTicket(context.Background(), "PAY-101")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if latest.ID != fresh.ID || latest.AttemptID != 2 || latest.LogicalID != oldID {
+		t.Fatalf("ticket lookup = %+v, want latest fresh attempt %q", latest, fresh.ID)
+	}
+	if current.State != run.StateWaiting && current.State != run.StateRunning {
+		t.Fatalf("fresh attempt state = %q, want active node state", current.State)
+	}
+	if got := log.count("prepareRestart:PAY-101"); got != 1 {
+		t.Fatalf("restart preparation calls = %d, want 1", got)
+	}
+	if len(fr.envs) != 1 {
+		t.Fatalf("restart created a second ticket environment: %d", len(fr.envs))
+	}
+	if fr.liveTerminals() != 1 {
+		t.Fatalf("restart left %d live terminals, want one fresh node terminal", fr.liveTerminals())
+	}
+}
+
+func TestRestartStatusConflictIsVisibleAndRecovers(t *testing.T) {
+	log := newEventLog()
+	sys := newFakeTaskSystem(log)
+	fr := newFakeRunner(log)
+	repos := repoRegistryWith("payments", sys)
+	wf := linearWorkflow(false)
+	workflows := &workflow.Registry{}
+	workflows.Replace(&wf)
+	engine := newEngine(t, goworkflows.Dependencies{Repos: repos, Runner: fr, Harness: newFakeHarness(log)})
+	oldID, err := startRun(engine, wf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 10*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), oldID)
+		return r.CurrentNode == "coding"
+	})
+	if err := engine.CancelRun(context.Background(), oldID, "operator requested restart"); err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), oldID)
+		return r.State == run.StateCanceled
+	})
+
+	sys.setStartConflict(true)
+	manager := &run.RunManager{Executor: engine, Runs: engine, Repos: repos, Workflows: workflows}
+	fresh, err := manager.RestartByTicket(context.Background(), "PAY-101")
+	if err != nil {
+		t.Fatal(err)
+	}
+	waitFor(t, 30*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), fresh.ID)
+		return r.State == run.StateBlocked
+	})
+	blocked, err := engine.GetRun(context.Background(), fresh.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(blocked.LastError, "Move ticket PAY-101 to an allowed active start status") {
+		t.Fatalf("blocked LastError = %q, want actionable start-status guidance", blocked.LastError)
+	}
+
+	sys.setStartConflict(false)
+	waitFor(t, 60*time.Second, func() bool {
+		r, _ := engine.GetRun(context.Background(), fresh.ID)
+		return r.CurrentNode == "coding" && r.CurrentNodeVisitID != ""
+	})
+}
+
 func TestCancelDuringRunningActivity(t *testing.T) {
 	// Cancellation cannot interrupt an already-running activity; it waits
 	// for it to return, then runs cancellation cleanup.
@@ -444,6 +570,9 @@ func TestConflictMarksBlockedThenRecovers(t *testing.T) {
 	if r.LastError == "" {
 		t.Fatal("blocked run exposes no conflict error in LastError")
 	}
+	if !strings.Contains(r.LastError, "Restore the task-system state required for node coding") {
+		t.Fatalf("blocked LastError = %q, want actionable node-state guidance", r.LastError)
+	}
 	if sys.mailboxStatusOf("PAY-101-coding") == "Done" {
 		t.Fatal("mailbox completed while state was incompatible; no blind overwrite allowed")
 	}