relay-flow 0.2.2-alpha → 0.2.3-alpha

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"`

package/internal/run/run_manager_test.go

@@ -259,6 +259,106 @@ func TestDeterministicRunID(t *testing.T) {
 	}
 }
 
+func TestRestartByTicketCreatesNumericFreshAttempt(t *testing.T) {
+	log := newEventLog()
+	sys := &recordingSystem{log: log}
+	wf := testWorkflow("basicFlow")
+	latestWorkflow := testWorkflow("basicFlow")
+	latestNode := latestWorkflow.Nodes["coding"]
+	latestNode.Description = "latest workflow definition"
+	latestWorkflow.Nodes["coding"] = latestNode
+	logical := identity.NewRunID("payments", wf.Name, "PAY-101")
+	previous := run.Run{
+		ID: logical, LogicalID: logical, AttemptID: 1,
+		Repo: "payments", Workflow: wf.Name,
+		Ticket: task.TicketRef{ID: "1", Key: "PAY-101"}, State: run.StateCanceled,
+	}
+	queries := &fakeQueries{
+		byTicket: map[string]run.Run{"PAY-101": previous},
+		list:     []run.Run{previous},
+	}
+	exec := &fakeExecutor{log: log, created: true}
+	repos := repo.NewRegistry()
+	repos.Replace(testRepo(sys))
+	workflows := &workflow.Registry{}
+	workflows.Replace(latestWorkflow)
+	m := &run.RunManager{Executor: exec, Runs: queries, Repos: repos, Workflows: workflows}
+
+	got, err := m.RestartByTicket(context.Background(), "PAY-101")
+	if err != nil {
+		t.Fatalf("RestartByTicket failed: %v", err)
+	}
+	wantID := identity.NewAttemptRunID(logical, 2)
+	if got.ID != wantID || got.LogicalID != logical || got.AttemptID != 2 {
+		t.Fatalf("restart run = %+v, want ID=%q logical=%q attempt=2", got, wantID, logical)
+	}
+	if len(exec.ensures) != 1 {
+		t.Fatalf("EnsureRun calls = %d, want 1", len(exec.ensures))
+	}
+	start := exec.ensures[0]
+	if start.ID != wantID || start.AttemptID != 2 || start.LogicalID != logical {
+		t.Fatalf("restart start = %+v, want numeric attempt 2 and fenced ID", start)
+	}
+	if start.Workflow.Name != wf.Name || start.Workflow.Nodes["coding"].Description != "latest workflow definition" {
+		t.Fatalf("restart did not use latest workflow snapshot: %+v", start.Workflow)
+	}
+}
+
+func TestRestartByTicketIsIdempotentForActiveFreshAttempt(t *testing.T) {
+	attempt := run.Run{
+		ID: "payments/basicFlow/PAY-101~attempt~2", LogicalID: "payments/basicFlow/PAY-101", AttemptID: 2,
+		Repo: "payments", Workflow: "basicFlow", Ticket: task.TicketRef{Key: "PAY-101"}, State: run.StateBlocked,
+	}
+	queries := &fakeQueries{byTicket: map[string]run.Run{"PAY-101": attempt}}
+	exec := &fakeExecutor{log: newEventLog()}
+	m := &run.RunManager{Executor: exec, Runs: queries}
+	got, err := m.RestartByTicket(context.Background(), "PAY-101")
+	if err != nil {
+		t.Fatalf("idempotent restart failed: %v", err)
+	}
+	if got.ID != attempt.ID || len(exec.ensures) != 0 {
+		t.Fatalf("idempotent restart = %+v, EnsureRun calls=%d", got, len(exec.ensures))
+	}
+}
+
+func TestRestartByTicketWaitsForCancelingAttempt(t *testing.T) {
+	attempt := run.Run{
+		ID: "payments/basicFlow/PAY-101", LogicalID: "payments/basicFlow/PAY-101", AttemptID: 1,
+		Repo: "payments", Workflow: "basicFlow", Ticket: task.TicketRef{Key: "PAY-101"}, State: run.StateCanceling,
+	}
+	queries := &fakeQueries{byTicket: map[string]run.Run{"PAY-101": attempt}}
+	m := &run.RunManager{Executor: &fakeExecutor{log: newEventLog()}, Runs: queries}
+	_, err := m.RestartByTicket(context.Background(), "PAY-101")
+	if !errors.Is(err, run.ErrRestartConflict) {
+		t.Fatalf("restart error = %v, want ErrRestartConflict", err)
+	}
+	if !strings.Contains(err.Error(), "wait for cancellation") {
+		t.Fatalf("restart error = %v, want actionable cancellation guidance", err)
+	}
+}
+
+func TestEnsureRunReusesActiveRestartAttempt(t *testing.T) {
+	log := newEventLog()
+	sys := &recordingSystem{log: log, hasCancel: true}
+	logical := identity.NewRunID("payments", "basicFlow", "PAY-101")
+	attempt := run.Run{
+		ID: identity.NewAttemptRunID(logical, 2), LogicalID: logical, AttemptID: 2,
+		Repo: "payments", Workflow: "basicFlow", Ticket: task.TicketRef{Key: "PAY-101"}, State: run.StateBlocked,
+	}
+	exec := &fakeExecutor{log: log}
+	m := &run.RunManager{Executor: exec, Runs: &fakeQueries{list: []run.Run{attempt}}}
+	ticket := task.Ticket{ID: "1", Key: "PAY-101", WorkflowClaims: []string{"wf:basicFlow"}}
+	if err := m.EnsureRun(context.Background(), testRepo(sys), testWorkflow("basicFlow"), ticket); err != nil {
+		t.Fatal(err)
+	}
+	if len(exec.ensures) != 1 || exec.ensures[0].ID != attempt.ID {
+		t.Fatalf("ensures = %+v, want active restart ID %q", exec.ensures, attempt.ID)
+	}
+	if sys.hasCommentN != 0 {
+		t.Fatal("active restart attempt checked cancellation marker")
+	}
+}
+
 func TestCancelByTicketResolvesActiveRun(t *testing.T) {
 	rid := identity.NewRunID("payments", "basicFlow", "PAY-101")
 	queries := &fakeQueries{byTicket: map[string]run.Run{

package/internal/server/api_test.go

@@ -3,8 +3,10 @@ package server_test
 import (
 	"bytes"
 	"encoding/json"
+	"fmt"
 	"io"
 	"net/http"
+	"strings"
 	"testing"
 	"time"
 
@@ -211,6 +213,58 @@ func TestRepoAndRunEndpoints(t *testing.T) {
 	}
 }
 
+func TestRunRestartEndpointReturnsFreshAttempt(t *testing.T) {
+	want := run.Run{
+		ID: "payments/basicFlow/PAY-101~attempt~2", LogicalID: "payments/basicFlow/PAY-101", AttemptID: 2,
+		Repo: "payments", Workflow: "basicFlow", Ticket: task.TicketRef{Key: "PAY-101"}, State: run.StateStarting,
+	}
+	fake := &fakeServices{restartRun: want}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+
+	code, env := do(t, c, http.MethodPost, "http://relay/runs/by-ticket/PAY-101/restart", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("POST restart: code=%d env=%+v", code, env)
+	}
+	if !bytes.Contains(env.Data, []byte(`"attemptId":2`)) ||
+		!bytes.Contains(env.Data, []byte(`"logicalRunId":"payments/basicFlow/PAY-101"`)) {
+		t.Fatalf("restart response omitted attempt identity: %s", env.Data)
+	}
+	if len(fake.restarts) != 1 || fake.restarts[0] != "PAY-101" {
+		t.Fatalf("restart calls = %v", fake.restarts)
+	}
+}
+
+func TestRunRestartConflictMapsTo409(t *testing.T) {
+	fake := &fakeServices{restartErr: fmt.Errorf("%w: ticket is still canceling", run.ErrRestartConflict)}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+	code, env := do(t, c, http.MethodPost, "http://relay/runs/by-ticket/PAY-101/restart", nil)
+	if code != http.StatusConflict || env.OK || env.Error == nil || !strings.Contains(env.Error.Message, "ticket is still canceling") {
+		t.Fatalf("restart conflict: code=%d env=%+v", code, env)
+	}
+}
+
+func TestBlockedRunGetShowsStatusAction(t *testing.T) {
+	blocked := run.Run{
+		ID: "payments/basicFlow/PAY-101~attempt~2", LogicalID: "payments/basicFlow/PAY-101", AttemptID: 2,
+		State: run.StateBlocked, CurrentNode: "start",
+		Ticket:    task.TicketRef{Key: "PAY-101"},
+		LastError: "Human-owned ticket status \"Blocked\" conflicts with the workflow start transition. Move ticket PAY-101 to an allowed active start status; relay-flow will retry automatically",
+	}
+	c, cleanup := startHandler(t, &fakeServices{runs: []run.Run{blocked}})
+	defer cleanup()
+	code, env := do(t, c, http.MethodGet, "http://relay/runs/by-ticket/PAY-101", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("GET blocked run: code=%d env=%+v", code, env)
+	}
+	for _, want := range []string{`"state":"blocked"`, `"currentNode":"start"`, `allowed active start status`, `automatically`} {
+		if !bytes.Contains(env.Data, []byte(want)) {
+			t.Fatalf("blocked run response missing %q: %s", want, env.Data)
+		}
+	}
+}
+
 func TestRunEndpointsExposeRetryDetails(t *testing.T) {
 	next := time.Now().UTC().Add(time.Minute)
 	retrying := run.Run{

package/internal/server/client.go

@@ -205,6 +205,17 @@ func (c *Client) RegisterNodeSession(ctx context.Context, registration run.NodeR
 	return ack, nil
 }
 
+// RestartRun creates or returns the active fresh attempt for a canceled
+// ticket. The server resolves the current repo/workflow and task-system
+// boundaries; the client only transports the command.
+func (c *Client) RestartRun(ctx context.Context, ticket string) (run.Run, error) {
+	var out run.Run
+	if err := c.call(ctx, http.MethodPost, "/runs/by-ticket/"+url.PathEscape(ticket)+"/restart", nil, &out); err != nil {
+		return run.Run{}, err
+	}
+	return out, nil
+}
+
 // CancelRun cancels the active run for the given ticket with a reason.
 func (c *Client) CancelRun(ctx context.Context, ticket, reason string) error {
 	payload, _ := json.Marshal(map[string]string{"reason": reason})

package/internal/server/fixture_test.go

@@ -34,6 +34,9 @@ type fakeServices struct {
 	runtimeAck       run.NodeRuntimeRegistrationAck
 	processedReports map[string]bool
 	submittedReports int
+	restartRun       run.Run
+	restartErr       error
+	restarts         []string
 }
 
 func (f *fakeServices) SubmitWorkflow(_ context.Context, yaml []byte) (*workflow.Workflow, error) {
@@ -79,6 +82,21 @@ func (f *fakeServices) GetRunByTicket(_ context.Context, ticket string) (run.Run
 	}
 	return run.Run{}, errNotFound{ticket}
 }
+func (f *fakeServices) RestartRun(_ context.Context, ticket string) (run.Run, error) {
+	f.restarts = append(f.restarts, ticket)
+	if f.restartErr != nil {
+		return run.Run{}, f.restartErr
+	}
+	if f.restartRun.ID != "" {
+		return f.restartRun, nil
+	}
+	for _, r := range f.runs {
+		if r.Ticket.Key == ticket {
+			return r, nil
+		}
+	}
+	return run.Run{}, errNotFound{ticket}
+}
 func (f *fakeServices) CancelRun(_ context.Context, ticket, _ string) error {
 	for i, r := range f.runs {
 		if r.Ticket.Key == ticket {

package/internal/server/server.go

@@ -31,6 +31,7 @@ type Deps interface {
 	// Runs
 	ListRuns(ctx context.Context, filter run.Filter) ([]run.Run, error)
 	GetRunByTicket(ctx context.Context, ticket string) (run.Run, error)
+	RestartRun(ctx context.Context, ticket string) (run.Run, error)
 	CancelRun(ctx context.Context, ticket, reason string) error
 
 	// Reports
@@ -117,6 +118,8 @@ func writeEnv(w http.ResponseWriter, status int, env envelope) {
 // anything else is an unexpected 500.
 func mapErr(w http.ResponseWriter, err error) {
 	switch {
+	case errors.Is(err, run.ErrRestartConflict):
+		writeErr(w, http.StatusConflict, "conflict", err.Error())
 	case errors.Is(err, ErrNotFound):
 		writeErr(w, http.StatusNotFound, "notFound", err.Error())
 	case errors.Is(err, ErrConflict):
@@ -475,6 +478,7 @@ func (s *server) handleRuns(w http.ResponseWriter, r *http.Request) {
 
 func (s *server) handleRunByTicket(w http.ResponseWriter, r *http.Request) {
 	// /runs/by-ticket/{key}           GET
+	// /runs/by-ticket/{key}/restart   POST
 	// /runs/by-ticket/{key}/cancel    POST
 	rest := strings.TrimPrefix(r.URL.Path, "/runs/by-ticket/")
 	parts := strings.Split(rest, "/")
@@ -490,6 +494,18 @@ func (s *server) handleRunByTicket(w http.ResponseWriter, r *http.Request) {
 		writeOK(w, http.StatusOK, rn)
 		return
 	}
+	if len(parts) == 2 && parts[0] != "" && parts[1] == "restart" {
+		if !methodOnly(w, r, http.MethodPost) {
+			return
+		}
+		rn, err := s.deps.RestartRun(r.Context(), parts[0])
+		if err != nil {
+			mapErr(w, err)
+			return
+		}
+		writeOK(w, http.StatusOK, rn)
+		return
+	}
 	if len(parts) == 2 && parts[0] != "" && parts[1] == "cancel" {
 		if !methodOnly(w, r, http.MethodPost) {
 			return

package/internal/task/beads/beads.go

@@ -809,6 +809,21 @@ func (s *system) lifecycleDefaults(builtin config.RawValues) config.RawValues {
 	return config.Merge(builtin, inherited)
 }
 
+// PrepareRestart reopens relay-owned mailbox state for a new explicit
+// attempt. The parent is deliberately not changed here; the start task
+// configuration checks the parent's current state and leaves a human-owned
+// Blocked/Deferred/Closed status untouched. Mailbox states outside the
+// relay-owned open/in_progress/closed set return a conflict.
+func (s *system) PrepareRestart(ctx context.Context, _ task.TicketRef, mailboxes []task.Mailbox) error {
+	for _, mailbox := range mailboxes {
+		if err := s.reconcileIssue(ctx, mailbox.Key,
+			[]string{statusOpen, statusInProgress, statusClosed}, statusOpen, ""); err != nil {
+			return fmt.Errorf("reopen mailbox %s for restart: %w", mailbox.Key, err)
+		}
+	}
+	return nil
+}
+
 // ResetForRecovery reopens the parent and every known mailbox, clearing any
 // deferred state while preserving comments, labels, descriptions, history,
 // and issues themselves.
@@ -837,4 +852,5 @@ func (s *system) ResetForRecovery(ctx context.Context, parent task.TicketRef, ma
 var (
 	_ task.System            = (*system)(nil)
 	_ task.LifecycleDefaults = (*system)(nil)
+	_ task.RestartPreparer   = (*system)(nil)
 )