relay-flow 0.2.2-alpha → 0.2.3-alpha

package/README.md

@@ -25,7 +25,7 @@ This is a ground-up rewrite. The previous per-workflow, in-memory daemon is gone
 go install github.com/rajpopat27/relay-flow/cmd/relay-flow@latest
 ```
 
-OpenCode plugin: add `"relay-flow-plugin"` to the `plugin` array in your repo's `opencode.json`:
+OpenCode plugin configuration uses both entrypoints. The server entrypoint is listed in `opencode.json`:
 
 ```json
 {
@@ -34,7 +34,22 @@ OpenCode plugin: add `"relay-flow-plugin"` to the `plugin` array in your repo's
 }
 ```
 
-The plugin is the report-path half of the harness contract: it registers each emitted harness session with `{runId, node, sessionId}`, parses the agent's structured report, applies the agent/HITL nudge policy, and delivers `{runId, node, reportId, report}` via `relay-flow report` with retry. `reportId` comes from the harness session/message identity; `nodeVisitID` is internal and is never part of either plugin payload.
+The native HITL approval entrypoint is listed in `.opencode/tui.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["relay-flow-plugin"]
+}
+```
+
+The OpenCode harness adds both entries when a repo is registered. The server
+entrypoint registers sessions, handles agent reports, and nudges invalid agent
+output. The TUI entrypoint handles only HITL reports: after a valid completed
+assistant report it shows a native Approve/Reject dialog. Approval delivers
+`{runId, node, reportId, report}` via `relay-flow report` with retry; rejection
+delivers nothing. `reportId` comes from the harness session/message identity;
+`nodeVisitID` is internal and is never part of either plugin payload.
 
 ### One-time machine setup
 
@@ -309,7 +324,27 @@ EXPECTED RESULT: ...
 
 The labels above are fixed; configurable templates do not change the parsed report contract. The plugin submits one `report` object containing both lower-camel `summary` and `feedback` objects. Relay-flow validates that complete shape once, renders `summaryReport` through the task system's summary-comment template on the current mailbox, and renders `feedbackReport` through its feedback-comment template on only the selected next mailbox. `None` is the literal marker for an intentionally empty section. When `NEXT STEP` is `end`, every FEEDBACK field must be `None` and no feedback comment is written.
 
-The plugin delivers `{runId, node, reportId, report}` as one JSON object via `relay-flow report` stdin with the shared backoff (initial 2s, factor 2, jitter 0.2, max 5m) until acknowledged. It derives `reportId` from the harness session/message identity. Duplicate/stale reports are acked safely with no repeated graph effects. Invalid agent output is nudged; invalid HITL output stays silent.
+The plugin delivers `{runId, node, reportId, report}` as one JSON object via `relay-flow report` stdin with the shared backoff (initial 2s, factor 2, jitter 0.2, max 5m) until acknowledged. It derives `reportId` from the harness session/message identity. Duplicate/stale reports are acked safely with no repeated graph effects. Invalid agent output is nudged; invalid or missing HITL output stays silent, while a valid HITL report opens the native TUI approval dialog. Relay-flow HITL approval does not use OpenCode's Question tool.
+
+---
+
+## Canceled run restart
+
+Cancellation is permanent for the current execution. A canceled ticket is not
+restarted by polling or by a ticket-status change. Start a fresh attempt
+explicitly:
+
+```sh
+relay-flow run restart --ticket PAY-101
+```
+
+The new attempt starts at `start`, preserves the existing worktree/mailboxes/
+comments/labels, and uses a numeric attempt ID (`2`, `3`, ...), with a fenced
+execution ID such as `payments/basicFlow/PAY-101~attempt~2`. If a human has
+moved the parent ticket to an incompatible status, `run get` shows `blocked`
+with an instruction to move it to an allowed active start status; relay-flow
+retries automatically and never overwrites the human-owned status. Done/Closed
+tickets are not reopened automatically.
 
 ---
 

package/cmd/relay-flow/commands_test.go

@@ -47,7 +47,7 @@ func TestCommandSurfaceExists(t *testing.T) {
 		{"workflow", "submit", "--file", "x.yaml"}, {"workflow", "remove", "--name", "x"},
 		{"workflow", "list"}, {"workflow", "get", "--name", "x"},
 		{"repo", "register"}, {"repo", "remove", "--name", "x"}, {"repo", "list"}, {"repo", "get", "--name", "x"},
-		{"run", "list"}, {"run", "get", "--ticket", "PAY-101"}, {"run", "cancel", "--ticket", "PAY-101"},
+		{"run", "list"}, {"run", "get", "--ticket", "PAY-101"}, {"run", "restart", "--ticket", "PAY-101"}, {"run", "cancel", "--ticket", "PAY-101"},
 	}
 	for _, argv := range commands {
 		// Recognized commands do not exit 2 ("usage/unknown"); they may exit
@@ -75,6 +75,7 @@ func TestRequiredFlagMissingExits2(t *testing.T) {
 		{"repo", "remove"},     // missing --name
 		{"repo", "get"},        // missing --name
 		{"run", "get"},         // missing --ticket
+		{"run", "restart"},     // missing --ticket
 		{"run", "cancel"},      // missing --ticket
 	} {
 		if code := cli(t, home, "", argv...); code != 2 {
@@ -1004,6 +1005,9 @@ func (s *ackServer) ListRuns(context.Context, runsvc.Filter) ([]runsvc.Run, erro
 func (s *ackServer) GetRunByTicket(context.Context, string) (runsvc.Run, error) {
 	panic("unreachable")
 }
+func (s *ackServer) RestartRun(context.Context, string) (runsvc.Run, error) {
+	panic("unreachable")
+}
 func (s *ackServer) CancelRun(context.Context, string, string) error { panic("unreachable") }
 func (s *ackServer) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) {
 	panic("unreachable")

package/cmd/relay-flow/main.go

@@ -149,6 +149,7 @@ Usage:
 
   relay-flow run list
   relay-flow run get --ticket <key>
+  relay-flow run restart --ticket <key>
   relay-flow run cancel --ticket <key>`)
 }
 
@@ -946,6 +947,25 @@ func cmdRun(c *server.Client, args []string) int {
 		enc.SetIndent("", "  ")
 		_ = enc.Encode(rn)
 		return exitOK
+	case "restart":
+		fs := flag.NewFlagSet("run restart", flag.ContinueOnError)
+		ticket := fs.String("ticket", "", "ticket key")
+		if err := fs.Parse(args[1:]); err != nil {
+			return exitUsage
+		}
+		if *ticket == "" {
+			fmt.Fprintln(os.Stderr, "run restart: --ticket is required")
+			return exitUsage
+		}
+		rn, err := c.RestartRun(context.Background(), *ticket)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		enc := json.NewEncoder(os.Stdout)
+		enc.SetIndent("", "  ")
+		_ = enc.Encode(rn)
+		return exitOK
 	case "cancel":
 		fs := flag.NewFlagSet("run cancel", flag.ContinueOnError)
 		ticket := fs.String("ticket", "", "ticket key")
@@ -968,7 +988,11 @@ func cmdRun(c *server.Client, args []string) int {
 }
 
 func formatRunListRow(r runsvc.Run) string {
-	row := fmt.Sprintf("%s\t%s\t%s\t%s", r.ID, r.Ticket.Key, r.Workflow, r.State)
+	attempt := r.AttemptID
+	if attempt == 0 {
+		attempt = 1
+	}
+	row := fmt.Sprintf("%s\t%s\t%s\t%s\tattempt=%d", r.ID, r.Ticket.Key, r.Workflow, r.State, attempt)
 	if r.Retry != nil {
 		row += fmt.Sprintf("\tretrying attempt=%d next=%s error=%q",
 			r.Retry.Attempt, r.Retry.NextRetryAt.Format(time.RFC3339), r.Retry.LastError)

package/cmd/relay-flow/serve.go

@@ -249,6 +249,8 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 	// the SAME registry by pointer (via replaceInternal), so the engine,
 	// pollers, and handlers observe one in-memory repo set.
 	wfSvc := workflow.NewService(store, engine, repoExists{repoReg})
+	runManager.Repos = repoReg
+	runManager.Workflows = wfSvc.Registry()
 	wfSvc.Gate = lifecycleGate
 	wfSvc.ValidateTaskConfig = workflowConfigValidator(repoReg)
 	// Submit/Remove must also rebuild repo bindings under the gate (spec
@@ -455,6 +457,16 @@ func (d *serveDeps) ListRuns(ctx context.Context, filter runsvc.Filter) ([]runsv
 func (d *serveDeps) GetRunByTicket(ctx context.Context, ticket string) (runsvc.Run, error) {
 	return d.engine.FindRunByTicket(ctx, ticket)
 }
+func (d *serveDeps) RestartRun(ctx context.Context, ticket string) (runsvc.Run, error) {
+	rn, err := d.runManager.RestartByTicket(ctx, ticket)
+	if err != nil {
+		if errors.Is(err, runsvc.ErrRestartConflict) {
+			return runsvc.Run{}, fmt.Errorf("%w: %v", server.ErrConflict, err)
+		}
+		return runsvc.Run{}, err
+	}
+	return rn, nil
+}
 func (d *serveDeps) CancelRun(ctx context.Context, ticket, reason string) error {
 	return d.runManager.CancelByTicket(ctx, ticket, reason)
 }

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 = ?`