relay-flow 0.2.8-alpha → 0.2.10-alpha

package/internal/execution/projection/detail_test.go

@@ -0,0 +1,259 @@
+package projection_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/run"
+)
+
+func TestLegacyNullCreationAndDurationRemainUnavailable(t *testing.T) {
+	ctx := context.Background()
+	p, db := openProjection(t)
+	now := time.Now().UTC()
+	if _, err := db.Exec(`INSERT INTO relay_runs (id, repo, workflow, ticket_id, ticket_key, state, started_at, updated_at) VALUES (?, 'repo', 'workflow', 'T-LEGACY', 'T-LEGACY', 'waiting', ?, ?)`, "legacy-null", now, now); err != nil {
+		t.Fatal(err)
+	}
+	detail, err := p.GetDetail(ctx, "legacy-null")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if detail.CreatedAt != nil {
+		t.Fatalf("legacy CreatedAt = %v, want nil", detail.CreatedAt)
+	}
+	if err := p.UpsertStep(ctx, run.StepEntry{RunID: "legacy-null", Sequence: 1, Node: "coding", Status: run.StepRunning}); err != nil {
+		t.Fatal(err)
+	}
+	steps, err := p.ListSteps(ctx, "legacy-null")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != 1 || steps[0].DurationKnown {
+		t.Fatalf("legacy unknown duration = %#v", steps)
+	}
+}
+
+func TestStepProjectionIsIdempotentAndDerivesDetail(t *testing.T) {
+	ctx := context.Background()
+	p, _ := openProjection(t)
+	start := projectionStart("detail-run", "PAY-DETAIL")
+	started := time.Now().UTC().Add(-2 * time.Minute)
+	if err := p.InsertStart(ctx, start, started); err != nil {
+		t.Fatal(err)
+	}
+	finished := started.Add(time.Minute)
+	step := run.StepEntry{
+		RunID: start.ID, Sequence: 1, Node: "coding", NodeVisitID: "visit-1", NodeType: "agent",
+		Status: run.StepSucceeded, StartedAt: &started, FinishedAt: &finished,
+		Message: "report accepted", Route: "end", Runtime: "coder", Resource: "harness",
+	}
+	if err := p.UpsertStep(ctx, step); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpsertStep(ctx, step); err != nil {
+		t.Fatal(err)
+	}
+	steps, err := p.ListSteps(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != 1 || steps[0].NodeVisitID != step.NodeVisitID || steps[0].Route != "end" || steps[0].Duration <= 0 {
+		t.Fatalf("steps = %#v", steps)
+	}
+	detail, err := p.GetDetail(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if detail.Progress.Completed != 1 || detail.Progress.Total != 1 || detail.ResourcesDuration.Harness <= 0 {
+		t.Fatalf("detail = %#v", detail)
+	}
+	if detail.Conditions.Completed {
+		t.Fatal("starting run was reported completed")
+	}
+}
+
+func TestStepUpsertDoesNotRegressTerminalVisit(t *testing.T) {
+	ctx := context.Background()
+	p, _ := openProjection(t)
+	start := projectionStart("monotonic-run", "PAY-MONOTONIC")
+	if err := p.InsertStart(ctx, start, time.Now().UTC()); err != nil {
+		t.Fatal(err)
+	}
+	finished := time.Now().UTC()
+	terminal := run.StepEntry{RunID: start.ID, Sequence: 1, Node: "coding", NodeVisitID: "visit-1", Status: run.StepSucceeded, FinishedAt: &finished, Message: "accepted", Route: "end"}
+	if err := p.UpsertStep(ctx, terminal); err != nil {
+		t.Fatal(err)
+	}
+	stale := terminal
+	stale.Status, stale.Message, stale.Route = run.StepRunning, "stale retry", "coding"
+	if err := p.UpsertStep(ctx, stale); err != nil {
+		t.Fatal(err)
+	}
+	steps, err := p.ListSteps(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != 1 || steps[0].Status != run.StepSucceeded || steps[0].Message != "accepted" || steps[0].Route != "end" {
+		t.Fatalf("stale write regressed terminal step: %#v", steps)
+	}
+}
+
+func TestBranchLoopVisitsRemainDistinctAndNested(t *testing.T) {
+	ctx := context.Background()
+	p, _ := openProjection(t)
+	start := projectionStart("branch-loop", "PAY-BRANCH")
+	if err := p.InsertStart(ctx, start, time.Now().UTC()); err != nil {
+		t.Fatal(err)
+	}
+	steps := []run.StepEntry{
+		{RunID: start.ID, Sequence: 1, Node: "coding", NodeVisitID: "visit-coding-1", Status: run.StepSucceeded, Depth: 1},
+		{RunID: start.ID, Sequence: 2, Node: "review", NodeVisitID: "visit-review-1", Status: run.StepSucceeded, Depth: 1},
+		{RunID: start.ID, Sequence: 3, Node: "coding", NodeVisitID: "visit-coding-2", ParentSequence: 1, Status: run.StepWaiting, Depth: 2},
+	}
+	for _, step := range steps {
+		if err := p.UpsertStep(ctx, step); err != nil {
+			t.Fatal(err)
+		}
+	}
+	got, err := p.ListSteps(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != len(steps) || got[2].NodeVisitID != "visit-coding-2" || got[2].ParentSequence != 1 || got[2].Depth != 2 {
+		t.Fatalf("branch/loop steps = %#v", got)
+	}
+}
+
+func TestStepProjectionFailureDoesNotBlockAuthoritativeRunState(t *testing.T) {
+	ctx := context.Background()
+	p, db := openProjection(t)
+	start := projectionStart("projection-failure", "PAY-PROJECTION")
+	if err := p.InsertStart(ctx, start, time.Now().UTC()); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.Exec(`DROP TABLE relay_run_steps`); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpdateState(ctx, start.ID, run.StateWaiting, "", nil); err != nil {
+		t.Fatalf("authoritative state update failed with missing display table: %v", err)
+	}
+	got, err := p.Get(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.State != run.StateWaiting {
+		t.Fatalf("state = %s, want waiting", got.State)
+	}
+}
+
+func TestTerminalStepTimingIsStableAcrossLaterRunFinalization(t *testing.T) {
+	ctx := context.Background()
+	p, _ := openProjection(t)
+	start := projectionStart("stable-terminal", "PAY-STABLE")
+	t0 := time.Now().UTC().Add(-2 * time.Minute)
+	t1 := t0.Add(20 * time.Second)
+	if err := p.InsertStart(ctx, start, t0); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpsertStep(ctx, run.StepEntry{RunID: start.ID, Sequence: 1, Node: "coding", Status: run.StepSucceeded, StartedAt: &t0, FinishedAt: &t1}); err != nil {
+		t.Fatal(err)
+	}
+	before, err := p.ListSteps(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(before) != 1 || before[0].FinishedAt == nil || before[0].Duration <= 0 {
+		t.Fatalf("initial terminal step = %#v", before)
+	}
+	finished := t1.Add(time.Minute)
+	if err := p.UpdateState(ctx, start.ID, run.StateCanceled, "canceled", &finished); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpdateState(ctx, start.ID, run.StateCanceled, "canceled", &finished); err != nil {
+		t.Fatal(err)
+	}
+	after, err := p.ListSteps(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(after) != 1 || !after[0].FinishedAt.Equal(*before[0].FinishedAt) || after[0].Duration != before[0].Duration {
+		t.Fatalf("terminal timing changed after run finalization: before=%#v after=%#v", before, after)
+	}
+}
+
+func TestCompletedRunFinalizesActiveStepWhenFinalUpsertIsMissing(t *testing.T) {
+	ctx := context.Background()
+	p, _ := openProjection(t)
+	start := projectionStart("complete-detail", "PAY-COMPLETE-DETAIL")
+	started := time.Now().UTC().Add(-time.Minute)
+	if err := p.InsertStart(ctx, start, started); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpsertStep(ctx, run.StepEntry{RunID: start.ID, Sequence: 1, Node: "end", Status: run.StepRunning, StartedAt: &started}); err != nil {
+		t.Fatal(err)
+	}
+	finished := time.Now().UTC()
+	if err := p.UpdateState(ctx, start.ID, run.StateCompleted, "", &finished); err != nil {
+		t.Fatal(err)
+	}
+	steps, err := p.ListSteps(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != 1 || steps[0].Status != run.StepSucceeded || steps[0].FinishedAt == nil || steps[0].Duration <= 0 {
+		t.Fatalf("completed step = %#v", steps)
+	}
+}
+
+func TestCanceledRunFinalizesCurrentStepTiming(t *testing.T) {
+	ctx := context.Background()
+	p, _ := openProjection(t)
+	start := projectionStart("cancel-detail", "PAY-CANCEL-DETAIL")
+	started := time.Now().UTC().Add(-time.Minute)
+	if err := p.InsertStart(ctx, start, started); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpsertStep(ctx, run.StepEntry{RunID: start.ID, Sequence: 1, Node: "coding", Status: run.StepRunning, StartedAt: &started}); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpdateState(ctx, start.ID, run.StateCanceling, "operator canceled", nil); err != nil {
+		t.Fatal(err)
+	}
+	finished := time.Now().UTC()
+	if err := p.UpdateState(ctx, start.ID, run.StateCanceled, "operator canceled", &finished); err != nil {
+		t.Fatal(err)
+	}
+	steps, err := p.ListSteps(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != 1 || steps[0].Status != run.StepCanceled || steps[0].FinishedAt == nil || steps[0].Duration <= 0 {
+		t.Fatalf("canceled step = %#v", steps)
+	}
+}
+
+func TestSetupConflictMarksCurrentStepBlocked(t *testing.T) {
+	ctx := context.Background()
+	p, _ := openProjection(t)
+	start := projectionStart("setup-conflict", "PAY-SETUP")
+	if err := p.InsertStart(ctx, start, time.Now().UTC()); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpsertStep(ctx, run.StepEntry{RunID: start.ID, Sequence: 1, Node: "coding", Status: run.StepRunning}); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.UpdateState(ctx, start.ID, run.StateBlocked, "runner setup conflict", nil); err != nil {
+		t.Fatal(err)
+	}
+	steps, err := p.ListSteps(ctx, start.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(steps) != 1 || steps[0].Status != run.StepBlocked || steps[0].Message != "runner setup conflict" {
+		t.Fatalf("blocked setup step = %#v", steps)
+	}
+	if steps[0].DurationKnown {
+		t.Fatal("unknown setup duration was fabricated as known")
+	}
+}

package/internal/execution/projection/projection.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"errors"
 	"fmt"
+	"log/slog"
 	"os"
 	"strings"
 	"sync"
@@ -117,6 +118,7 @@ CREATE TABLE IF NOT EXISTS relay_runs (
     workflow TEXT NOT NULL,
     ticket_id TEXT NOT NULL,
     ticket_key TEXT NOT NULL,
+    created_at DATETIME,
     state TEXT NOT NULL,
     current_node TEXT,
     current_node_visit_id TEXT,
@@ -158,6 +160,28 @@ CREATE TABLE IF NOT EXISTS relay_node_sessions (
     PRIMARY KEY (run_id, node, session_id),
     FOREIGN KEY (run_id) REFERENCES relay_runs(id) ON DELETE CASCADE
 );
+CREATE TABLE IF NOT EXISTS relay_run_steps (
+    run_id TEXT NOT NULL,
+    sequence INTEGER NOT NULL,
+    node TEXT NOT NULL,
+    node_visit_id TEXT,
+    node_type TEXT,
+    parent_sequence INTEGER,
+    depth INTEGER,
+    status TEXT NOT NULL,
+    started_at DATETIME,
+    finished_at DATETIME,
+    duration_ns INTEGER,
+    message TEXT,
+    selected_route TEXT,
+    runtime TEXT,
+    resource TEXT,
+    PRIMARY KEY (run_id, sequence),
+    FOREIGN KEY (run_id) REFERENCES relay_runs(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS relay_run_steps_run_order ON relay_run_steps (run_id, sequence);
+CREATE UNIQUE INDEX IF NOT EXISTS relay_run_steps_run_visit ON relay_run_steps (run_id, node_visit_id)
+    WHERE node_visit_id IS NOT NULL AND node_visit_id <> '';
 `
 
 func (p *RunProjection) migrate() error {
@@ -170,6 +194,7 @@ func (p *RunProjection) migrate() error {
 		"retry_error":    "TEXT",
 		"retry_attempt":  "INTEGER",
 		"next_retry_at":  "DATETIME",
+		"created_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 {
@@ -190,10 +215,24 @@ func (p *RunProjection) migrate() error {
 	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
 	}
+	for name, definition := range map[string]string{
+		"parent_sequence": "INTEGER",
+		"depth":           "INTEGER",
+	} {
+		var count int
+		if err := p.DB.QueryRow(`SELECT COUNT(1) FROM pragma_table_info('relay_run_steps') WHERE name = ?`, name).Scan(&count); err != nil {
+			return err
+		}
+		if count == 0 {
+			if _, err := p.DB.Exec(`ALTER TABLE relay_run_steps ADD COLUMN ` + name + ` ` + definition); err != nil {
+				return err
+			}
+		}
+	}
 	return nil
 }
 
-var errRunNotFound = errors.New("run not found")
+var errRunNotFound = run.ErrNotFound
 var errNodeRuntimeNotFound = errors.New("node runtime not found")
 
 // IsNotFound reports a missing projection row.
@@ -209,24 +248,86 @@ func (p *RunProjection) insertStart(ctx context.Context, s run.Start, now time.T
 		attemptID = 1
 	}
 	_, err := p.DB.ExecContext(ctx, `
-		INSERT INTO relay_runs (id, logical_run_id, attempt_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, created_at, state, started_at, updated_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 		ON CONFLICT(id) DO NOTHING`,
 		string(s.ID), string(logicalID), int64(attemptID), s.Repo, s.Workflow.Name, s.Ticket.ID, s.Ticket.Key,
-		string(run.StateStarting), now, now)
+		now, string(run.StateStarting), now, now)
 	return err
 }
 
 func (p *RunProjection) updateState(ctx context.Context, id run.ID, state run.State, lastErr string, finished *time.Time) error {
 	terminal := state == run.StateCompleted || state == run.StateCanceled
+	now := time.Now().UTC()
 	_, err := p.DB.ExecContext(ctx, `
 		UPDATE relay_runs SET state = ?, last_error = ?, updated_at = ?, finished_at = COALESCE(?, finished_at),
 			retry_error = CASE WHEN ? THEN NULL ELSE retry_error END,
 			retry_attempt = CASE WHEN ? THEN NULL ELSE retry_attempt END,
 			next_retry_at = CASE WHEN ? THEN NULL ELSE next_retry_at END
 		WHERE id = ?`,
-		string(state), lastErr, time.Now().UTC(), finished, terminal, terminal, terminal, string(id))
-	return err
+		string(state), lastErr, now, finished, terminal, terminal, terminal, string(id))
+	if err != nil {
+		return err
+	}
+	// Keep the derived timeline useful during retries and cancellation without
+	// making it an execution authority. Identify one active row first; a
+	// repeated terminal update with no active row is a no-op for the timeline.
+	stepStatus := stepStatusForRunState(state)
+	if stepStatus == "" {
+		return nil
+	}
+	var sequence int64
+	var startedAt sql.NullTime
+	lookupErr := p.DB.QueryRowContext(ctx, `
+		SELECT sequence, started_at FROM relay_run_steps
+		WHERE run_id = ? AND status IN ('running', 'waiting', 'blocked')
+		ORDER BY sequence DESC LIMIT 1`, string(id)).Scan(&sequence, &startedAt)
+	if errors.Is(lookupErr, sql.ErrNoRows) {
+		return nil
+	}
+	if lookupErr != nil {
+		// relay_run_steps is display/cache data. The authoritative relay_runs
+		// state update above has already succeeded and must not be retried just
+		// because this optional projection is unavailable.
+		slog.Warn("step projection state lookup unavailable", "runID", string(id), "state", state, "error", lookupErr)
+		return nil
+	}
+	var stepFinished any
+	if terminal {
+		if finished != nil {
+			stepFinished = *finished
+		} else {
+			stepFinished = now
+		}
+	}
+	result, err := p.DB.ExecContext(ctx, `
+		UPDATE relay_run_steps SET status = ?, message = CASE WHEN ? <> '' THEN ? ELSE message END,
+			finished_at = CASE WHEN ? THEN COALESCE(finished_at, ?) ELSE finished_at END
+		WHERE run_id = ? AND sequence = ? AND status IN ('running', 'waiting', 'blocked')`,
+		stepStatus, lastErr, lastErr, terminal, stepFinished,
+		string(id), sequence)
+	if err != nil {
+		slog.Warn("step projection state update unavailable", "runID", string(id), "state", state, "error", err)
+		return nil
+	}
+	updated, err := result.RowsAffected()
+	if err != nil || updated != 1 {
+		return nil
+	}
+	if terminal && startedAt.Valid {
+		endAt := now
+		if finished != nil {
+			endAt = *finished
+		}
+		duration := endAt.Sub(startedAt.Time)
+		if duration < 0 {
+			duration = 0
+		}
+		if _, durationErr := p.DB.ExecContext(ctx, `UPDATE relay_run_steps SET duration_ns = ? WHERE run_id = ? AND sequence = ?`, int64(duration), string(id), sequence); durationErr != nil {
+			slog.Warn("step projection duration update unavailable", "runID", string(id), "state", state, "error", durationErr)
+		}
+	}
+	return nil
 }
 
 func (p *RunProjection) updateRetry(ctx context.Context, id run.ID, status *run.RetryStatus) error {
@@ -271,6 +372,169 @@ func (p *RunProjection) updateNode(ctx context.Context, id run.ID, state run.Sta
 	return tx.Commit()
 }
 
+func stepStatusForRunState(state run.State) string {
+	switch state {
+	case run.StateRunning:
+		return string(run.StepRunning)
+	case run.StateWaiting:
+		return string(run.StepWaiting)
+	case run.StateBlocked:
+		return string(run.StepBlocked)
+	case run.StateCompleted:
+		return string(run.StepSucceeded)
+	case run.StateCanceled:
+		return string(run.StepCanceled)
+	default:
+		return ""
+	}
+}
+
+// upsertStep records one display row idempotently. The durable executor calls
+// this at existing lifecycle boundaries; no route or report decision reads
+// this table.
+func (p *RunProjection) upsertStep(ctx context.Context, step run.StepEntry) error {
+	if step.RunID == "" {
+		return fmt.Errorf("step projection requires a run id")
+	}
+	if step.Node == "" {
+		return fmt.Errorf("step projection requires a node")
+	}
+	if step.Status == "" {
+		return fmt.Errorf("step projection requires a status")
+	}
+	var startedAt, finishedAt any
+	if step.StartedAt != nil && !step.StartedAt.IsZero() {
+		startedAt = step.StartedAt.UTC()
+	}
+	if step.FinishedAt != nil && !step.FinishedAt.IsZero() {
+		finishedAt = step.FinishedAt.UTC()
+	}
+	_, err := p.DB.ExecContext(ctx, `
+		INSERT INTO relay_run_steps
+			(run_id, sequence, node, node_visit_id, node_type, parent_sequence, depth, status, started_at, finished_at,
+			 duration_ns, message, selected_route, runtime, resource)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT(run_id, sequence) DO UPDATE SET
+			node = excluded.node,
+			node_visit_id = COALESCE(NULLIF(excluded.node_visit_id, ''), relay_run_steps.node_visit_id),
+			node_type = COALESCE(NULLIF(excluded.node_type, ''), relay_run_steps.node_type),
+			parent_sequence = CASE WHEN excluded.parent_sequence <> 0 THEN excluded.parent_sequence ELSE relay_run_steps.parent_sequence END,
+			depth = CASE WHEN excluded.depth <> 0 THEN excluded.depth ELSE relay_run_steps.depth END,
+			status = CASE
+				WHEN relay_run_steps.status IN ('succeeded', 'failed', 'canceled') THEN relay_run_steps.status
+				WHEN relay_run_steps.status = 'blocked' AND excluded.status IN ('pending', 'running', 'waiting') THEN relay_run_steps.status
+				WHEN relay_run_steps.status = 'waiting' AND excluded.status IN ('pending', 'running') THEN relay_run_steps.status
+				WHEN relay_run_steps.status = 'running' AND excluded.status = 'pending' THEN relay_run_steps.status
+				ELSE excluded.status
+			END,
+			started_at = COALESCE(relay_run_steps.started_at, excluded.started_at),
+			finished_at = CASE
+				WHEN relay_run_steps.status IN ('succeeded', 'failed', 'canceled') THEN relay_run_steps.finished_at
+				ELSE COALESCE(excluded.finished_at, relay_run_steps.finished_at)
+			END,
+			duration_ns = CASE
+				WHEN relay_run_steps.status IN ('succeeded', 'failed', 'canceled') THEN relay_run_steps.duration_ns
+				WHEN excluded.duration_ns <> 0 THEN excluded.duration_ns
+				WHEN excluded.finished_at IS NOT NULL AND COALESCE(relay_run_steps.started_at, excluded.started_at) IS NOT NULL
+					THEN CAST((julianday(excluded.finished_at) - julianday(COALESCE(relay_run_steps.started_at, excluded.started_at))) * 86400000000000 AS INTEGER)
+				ELSE relay_run_steps.duration_ns
+			END,
+			message = CASE WHEN relay_run_steps.status IN ('succeeded', 'failed', 'canceled') THEN relay_run_steps.message ELSE COALESCE(NULLIF(excluded.message, ''), relay_run_steps.message) END,
+			selected_route = CASE WHEN relay_run_steps.status IN ('succeeded', 'failed', 'canceled') THEN relay_run_steps.selected_route ELSE COALESCE(NULLIF(excluded.selected_route, ''), relay_run_steps.selected_route) END,
+			runtime = COALESCE(NULLIF(excluded.runtime, ''), relay_run_steps.runtime),
+			resource = COALESCE(NULLIF(excluded.resource, ''), relay_run_steps.resource)`,
+		string(step.RunID), step.Sequence, step.Node, nullableString(string(step.NodeVisitID)),
+		nullableString(step.NodeType), step.ParentSequence, step.Depth, string(step.Status), startedAt, finishedAt,
+		durationNanos(step), nullableString(step.Message), nullableString(step.Route),
+		nullableString(step.Runtime), nullableString(step.Resource))
+	return err
+}
+
+func durationNanos(step run.StepEntry) any {
+	if step.Duration != 0 {
+		return int64(step.Duration)
+	}
+	if step.StartedAt != nil && step.FinishedAt != nil {
+		duration := step.FinishedAt.Sub(*step.StartedAt)
+		if duration < 0 {
+			duration = 0
+		}
+		return int64(duration)
+	}
+	if step.DurationKnown {
+		return int64(0)
+	}
+	return nil
+}
+
+func (p *RunProjection) listSteps(ctx context.Context, id run.ID) ([]run.StepEntry, error) {
+	rows, err := p.DB.QueryContext(ctx, `
+		SELECT run_id, sequence, node, node_visit_id, node_type, parent_sequence, depth, status,
+			started_at, finished_at, duration_ns, message, selected_route, runtime, resource
+		FROM relay_run_steps WHERE run_id = ? ORDER BY sequence`, string(id))
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	steps := make([]run.StepEntry, 0)
+	for rows.Next() {
+		var step run.StepEntry
+		var visit, nodeType, message, route, runtime, resource sql.NullString
+		var started, finished sql.NullTime
+		var duration, parentSequence, depth sql.NullInt64
+		if err := rows.Scan(&step.RunID, &step.Sequence, &step.Node, &visit, &nodeType,
+			&parentSequence, &depth, &step.Status, &started, &finished, &duration,
+			&message, &route, &runtime, &resource); err != nil {
+			return nil, err
+		}
+		step.NodeVisitID = run.NodeVisitID(visit.String)
+		if parentSequence.Valid {
+			step.ParentSequence = parentSequence.Int64
+		}
+		if depth.Valid {
+			step.Depth = int(depth.Int64)
+		}
+		step.NodeType, step.Message, step.Route = nodeType.String, message.String, route.String
+		step.Runtime, step.Resource = runtime.String, resource.String
+		if started.Valid {
+			t := started.Time.UTC()
+			step.StartedAt = &t
+		}
+		if finished.Valid {
+			t := finished.Time.UTC()
+			step.FinishedAt = &t
+		}
+		if duration.Valid {
+			step.Duration = time.Duration(duration.Int64)
+			step.DurationKnown = true
+		}
+		steps = append(steps, step)
+	}
+	return steps, rows.Err()
+}
+
+func (p *RunProjection) getDetail(ctx context.Context, id run.ID) (run.RunDetail, error) {
+	base, err := p.get(ctx, id)
+	if err != nil {
+		return run.RunDetail{}, err
+	}
+	detail := run.NewRunDetail(base)
+	var created sql.NullTime
+	if err := p.DB.QueryRowContext(ctx, `SELECT created_at FROM relay_runs WHERE id = ?`, string(id)).Scan(&created); err != nil {
+		return run.RunDetail{}, err
+	}
+	if created.Valid {
+		createdAt := created.Time.UTC()
+		detail.CreatedAt = &createdAt
+	}
+	detail.Steps, err = p.listSteps(ctx, id)
+	if err != nil {
+		return run.RunDetail{}, err
+	}
+	detail.DeriveInspectionFields(time.Now().UTC())
+	return detail, nil
+}
+
 func (p *RunProjection) getNodeRuntime(ctx context.Context, id run.ID, node string) (NodeRuntime, error) {
 	var rt NodeRuntime
 	var terminalID, sessionID sql.NullString
@@ -610,6 +874,10 @@ func (p *RunProjection) sweepRetention(ctx context.Context, olderThan time.Time)
 			tx.Rollback()
 			return ids, err
 		}
+		if _, err := tx.ExecContext(ctx, `DELETE FROM relay_run_steps WHERE run_id = ?`, id); err != nil {
+			tx.Rollback()
+			return ids, err
+		}
 		if _, err := tx.ExecContext(ctx, `DELETE FROM relay_runs WHERE id = ?`, id); err != nil {
 			tx.Rollback()
 			return ids, err
@@ -649,6 +917,22 @@ func (p *RunProjection) UpdateNode(ctx context.Context, id run.ID, state run.Sta
 	return p.updateNode(ctx, id, state, node, visit)
 }
 
+// UpsertStep records or updates one display-only execution step.
+func (p *RunProjection) UpsertStep(ctx context.Context, step run.StepEntry) error {
+	return p.upsertStep(ctx, step)
+}
+
+// ListSteps returns the ordered display-only execution timeline for a run.
+func (p *RunProjection) ListSteps(ctx context.Context, id run.ID) ([]run.StepEntry, error) {
+	return p.listSteps(ctx, id)
+}
+
+// GetDetail returns a run and its derived inspection data in one query
+// boundary. The result never drives durable execution.
+func (p *RunProjection) GetDetail(ctx context.Context, id run.ID) (run.RunDetail, error) {
+	return p.getDetail(ctx, id)
+}
+
 // GetNodeRuntime returns one node's persisted runtime binding.
 func (p *RunProjection) GetNodeRuntime(ctx context.Context, id run.ID, node string) (NodeRuntime, error) {
 	return p.getNodeRuntime(ctx, id, node)

package/internal/execution/projection/projection_test.go

@@ -80,6 +80,7 @@ func TestSharedProjectionSchemaAndQueries(t *testing.T) {
 		"relay_node_runtime",
 		"relay_node_sessions",
 		"relay_processed_reports",
+		"relay_run_steps",
 		"relay_runs",
 	}
 	if len(tables) != len(wantTables) {
@@ -209,8 +210,8 @@ func TestProjectionImplementationIsSharedByExecutorModes(t *testing.T) {
 			if err := db.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name LIKE 'relay_%'`).Scan(&count); err != nil {
 				t.Fatal(err)
 			}
-			if count != 5 {
-				t.Fatalf("relay schema table count = %d, want five shared tables", count)
+			if count != 6 {
+				t.Fatalf("relay schema table count = %d, want six shared tables", count)
 			}
 			if err := p.InsertStart(context.Background(), projectionStart(run.ID("run-"+mode), "PAY-"+mode), time.Now().UTC()); err != nil {
 				t.Fatalf("insert %s run through shared projection: %v", mode, err)

package/internal/execution/temporal/activities.go

@@ -411,6 +411,15 @@ func (a *Activities) CompleteMailbox(ctx context.Context, w run.Work, mailbox ta
 
 // Projection activities: idempotent read-model updates.
 
+func (a *Activities) ProjectionUpsertStep(ctx context.Context, step run.StepEntry) error {
+	if err := a.Runs.UpsertStep(ctx, step); err != nil {
+		// Step detail is a cache. Never let a display-projection failure block
+		// route selection, report acceptance, or durable graph progression.
+		slog.Warn("step projection unavailable", "runID", string(step.RunID), "node", step.Node, "sequence", step.Sequence, "error", err)
+	}
+	return nil
+}
+
 func (a *Activities) ProjectionUpdateNode(ctx context.Context, id run.ID, state run.State, node string, visit run.NodeVisitID) error {
 	return a.Runs.UpdateNode(ctx, id, state, node, visit)
 }

package/internal/execution/temporal/engine.go

@@ -362,6 +362,19 @@ func (e *Engine) GetRun(ctx context.Context, id run.ID) (run.Run, error) {
 func (e *Engine) FindRunByTicket(ctx context.Context, ticket string) (run.Run, error) {
 	return e.runs.FindByTicket(ctx, ticket)
 }
+func (e *Engine) GetRunDetail(ctx context.Context, id run.ID) (run.RunDetail, error) {
+	detail, err := e.runs.GetDetail(ctx, id)
+	if err != nil {
+		return run.RunDetail{}, err
+	}
+	// Static definitions only contribute explicit pending display rows. The
+	// derived projection is never consulted by Temporal workflow code.
+	if wf, wfErr := e.workflowFromHistory(ctx, id, ""); wfErr == nil {
+		detail.AddPendingNodes(*wf)
+		detail.DeriveInspectionFields(time.Now().UTC())
+	}
+	return detail, nil
+}
 func (e *Engine) ListRuns(ctx context.Context, filter run.Filter) ([]run.Run, error) {
 	return e.runs.List(ctx, filter)
 }