relay-flow 0.2.9-alpha → 0.2.11-alpha

package/internal/execution/temporal/operations.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log/slog"
+	"sort"
 	"time"
 
 	"github.com/rajpopat27/relay-flow/internal/execution/projection"
@@ -375,6 +377,160 @@ func (e *Engine) workflowStart(ctx context.Context, id, temporalRunID string) (r
 	return run.Start{}, fmt.Errorf("Temporal workflow %s has no WorkflowExecutionStarted snapshot", id)
 }
 
+func temporalStepRank(status run.StepStatus) int {
+	switch status {
+	case run.StepSucceeded, run.StepFailed, run.StepCanceled:
+		return 4
+	case run.StepBlocked:
+		return 3
+	case run.StepWaiting:
+		return 2
+	case run.StepRunning:
+		return 1
+	default:
+		return 0
+	}
+}
+
+func mergeTemporalStep(existing, incoming run.StepEntry) run.StepEntry {
+	if existing.RunID == "" {
+		return incoming
+	}
+	if temporalStepRank(existing.Status) >= 4 || temporalStepRank(incoming.Status) < temporalStepRank(existing.Status) {
+		return existing
+	}
+	if incoming.StartedAt == nil {
+		incoming.StartedAt = existing.StartedAt
+	}
+	if incoming.FinishedAt == nil {
+		incoming.FinishedAt = existing.FinishedAt
+	}
+	if incoming.Duration == 0 {
+		incoming.Duration = existing.Duration
+	}
+	incoming.DurationKnown = incoming.DurationKnown || existing.DurationKnown
+	if incoming.Message == "" {
+		incoming.Message = existing.Message
+	}
+	if incoming.Route == "" {
+		incoming.Route = existing.Route
+	}
+	if incoming.Runtime == "" {
+		incoming.Runtime = existing.Runtime
+	}
+	if incoming.Resource == "" {
+		incoming.Resource = existing.Resource
+	}
+	if incoming.ParentSequence == 0 {
+		incoming.ParentSequence = existing.ParentSequence
+	}
+	if incoming.Depth == 0 {
+		incoming.Depth = existing.Depth
+	}
+	return incoming
+}
+
+func applyTemporalProjectionState(steps map[int64]run.StepEntry, state run.State, message string, finished *time.Time) {
+	var selected int64
+	found := false
+	for sequence, step := range steps {
+		if step.Status != run.StepRunning && step.Status != run.StepWaiting && step.Status != run.StepBlocked {
+			continue
+		}
+		if !found || sequence > selected {
+			selected, found = sequence, true
+		}
+	}
+	if !found {
+		return
+	}
+	step := steps[selected]
+	switch state {
+	case run.StateWaiting:
+		step.Status = run.StepWaiting
+	case run.StateBlocked:
+		step.Status = run.StepBlocked
+	case run.StateCanceled, run.StateCanceling:
+		step.Status = run.StepCanceled
+	default:
+		return
+	}
+	if message != "" {
+		step.Message = message
+	}
+	if finished != nil && step.FinishedAt == nil {
+		finish := finished.UTC()
+		step.FinishedAt = &finish
+		if step.StartedAt != nil && !step.DurationKnown {
+			duration := finish.Sub(*step.StartedAt)
+			if duration < 0 {
+				duration = 0
+			}
+			step.Duration = duration
+			step.DurationKnown = true
+		}
+	}
+	steps[selected] = step
+}
+
+// stepsFromHistory reconstructs the display projection for a closed Temporal
+// execution when its workflow query handler is unavailable. It reads only
+// durable Temporal history; it does not call task-system, runner, or harness
+// boundaries and cannot affect execution.
+func (e *Engine) stepsFromHistory(ctx context.Context, id run.ID, temporalRunID string) ([]run.StepEntry, error) {
+	c, err := e.ready()
+	if err != nil {
+		return nil, err
+	}
+	iterator := c.GetWorkflowHistory(ctx, string(id), temporalRunID, false, enumspb.HISTORY_EVENT_FILTER_TYPE_ALL_EVENT)
+	bySequence := map[int64]run.StepEntry{}
+	for iterator.HasNext() {
+		event, err := iterator.Next()
+		if err != nil {
+			return nil, fmt.Errorf("read Temporal history for %s: %w", id, err)
+		}
+		attrs := event.GetActivityTaskScheduledEventAttributes()
+		if attrs == nil || attrs.GetActivityType() == nil || attrs.GetInput() == nil {
+			continue
+		}
+		name := attrs.GetActivityType().GetName()
+		payloads := attrs.GetInput().GetPayloads()
+		if len(payloads) == 0 {
+			continue
+		}
+		switch name {
+		case activityProjectionUpsertStep:
+			var step run.StepEntry
+			if err := converter.GetDefaultDataConverter().FromPayload(payloads[0], &step); err != nil {
+				continue
+			}
+			if step.RunID == "" {
+				step.RunID = id
+			}
+			bySequence[step.Sequence] = mergeTemporalStep(bySequence[step.Sequence], step)
+		case activityProjectionUpdateState:
+			var activityID run.ID
+			var state run.State
+			var message string
+			var finished *time.Time
+			if err := converter.GetDefaultDataConverter().FromPayloads(attrs.GetInput(), &activityID, &state, &message, &finished); err != nil || activityID != id {
+				continue
+			}
+			applyTemporalProjectionState(bySequence, state, message, finished)
+		}
+	}
+	sequences := make([]int64, 0, len(bySequence))
+	for sequence := range bySequence {
+		sequences = append(sequences, sequence)
+	}
+	sort.Slice(sequences, func(i, j int) bool { return sequences[i] < sequences[j] })
+	out := make([]run.StepEntry, 0, len(sequences))
+	for _, sequence := range sequences {
+		out = append(out, bySequence[sequence])
+	}
+	return out, nil
+}
+
 func stateForTemporalStatus(status enumspb.WorkflowExecutionStatus, closeTime *timestamppb.Timestamp) (run.State, *time.Time) {
 	var finished *time.Time
 	if closeTime != nil {
@@ -424,6 +580,12 @@ func (e *Engine) restoreProjection(ctx context.Context, info *workflowpb.Workflo
 				return err
 			}
 		}
+		for _, step := range state.Steps {
+			step.RunID = id
+			if err := e.runs.UpsertStep(ctx, step); err != nil {
+				slog.Warn("Temporal step projection restore write unavailable", "runID", string(id), "sequence", step.Sequence, "error", err)
+			}
+		}
 		if state.Run.State == run.StateCompleted || state.Run.State == run.StateCanceled {
 			finished := state.Run.FinishedAt
 			if finished == nil && info.CloseTime != nil {
@@ -451,5 +613,17 @@ func (e *Engine) restoreProjection(ctx context.Context, info *workflowpb.Workflo
 	if info.Status == enumspb.WORKFLOW_EXECUTION_STATUS_RUNNING {
 		return fmt.Errorf("query Temporal run-state for active workflow %s: %w", id, queryErr)
 	}
+	// Closed executions cannot always serve workflow queries. Rebuild the
+	// display timeline from scheduled projection activities in retained
+	// Temporal history instead of dropping all historical visits.
+	if steps, historyErr := e.stepsFromHistory(ctx, id, info.Execution.RunId); historyErr != nil {
+		slog.Warn("Temporal step projection history unavailable", "runID", string(id), "error", historyErr)
+	} else {
+		for _, step := range steps {
+			if err := e.runs.UpsertStep(ctx, step); err != nil {
+				slog.Warn("Temporal step projection rebuild write unavailable", "runID", string(id), "sequence", step.Sequence, "error", err)
+			}
+		}
+	}
 	return e.runs.UpdateState(ctx, id, stateValue, "", finished)
 }

package/internal/execution/temporal/operations_test.go

@@ -15,6 +15,42 @@ import (
 	_ "modernc.org/sqlite"
 )
 
+func TestApplyTemporalProjectionStateRebuildsCanceledTimingIdempotently(t *testing.T) {
+	started := time.Now().UTC().Add(-time.Minute)
+	finished := started.Add(30 * time.Second)
+	later := finished.Add(time.Minute)
+	steps := map[int64]run.StepEntry{1: {RunID: "run", Sequence: 1, Node: "coding", Status: run.StepRunning, StartedAt: &started}}
+	applyTemporalProjectionState(steps, run.StateCanceled, "operator canceled", &finished)
+	first := steps[1]
+	if first.Status != run.StepCanceled || first.FinishedAt == nil || !first.FinishedAt.Equal(finished) || first.Duration <= 0 {
+		t.Fatalf("rebuilt canceled step = %#v", first)
+	}
+	applyTemporalProjectionState(steps, run.StateCanceled, "operator canceled", &later)
+	second := steps[1]
+	if !second.FinishedAt.Equal(finished) || second.Duration != first.Duration {
+		t.Fatalf("repeated canceled rebuild changed timing: first=%#v second=%#v", first, second)
+	}
+	terminalFinished := started.Add(10 * time.Second)
+	steps[2] = run.StepEntry{RunID: "run", Sequence: 2, Node: "already-done", Status: run.StepSucceeded, StartedAt: &started, FinishedAt: &terminalFinished, Duration: 10 * time.Second, DurationKnown: true}
+	applyTemporalProjectionState(steps, run.StateCanceled, "operator canceled", &later)
+	if steps[2].Status != run.StepSucceeded || !steps[2].FinishedAt.Equal(terminalFinished) {
+		t.Fatalf("already-terminal step changed: %#v", steps[2])
+	}
+}
+
+func TestMergeTemporalStepPreservesResourceLabel(t *testing.T) {
+	existing := run.StepEntry{RunID: "run", Sequence: 1, Node: "coding", Status: run.StepRunning, Resource: "harness"}
+	incoming := run.StepEntry{RunID: "run", Sequence: 1, Node: "coding", Status: run.StepSucceeded, Message: "done"}
+	merged := mergeTemporalStep(existing, incoming)
+	if merged.Resource != "harness" || merged.Status != run.StepSucceeded || merged.Message != "done" {
+		t.Fatalf("merged step = %#v", merged)
+	}
+	withNewResource := mergeTemporalStep(merged, run.StepEntry{RunID: "run", Sequence: 1, Node: "coding", Status: run.StepSucceeded, Resource: "runner"})
+	if withNewResource.Resource != "harness" {
+		t.Fatalf("terminal resource was overwritten: %#v", withNewResource)
+	}
+}
+
 func TestValidateTemporalExecutionIdentity(t *testing.T) {
 	valid := func(workflowID, workflowType, taskQueue string) *workflowpb.WorkflowExecutionInfo {
 		return &workflowpb.WorkflowExecutionInfo{

package/internal/harness/opencode/opencode_test.go

@@ -14,7 +14,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-const configuredPlugin = "relay-flow-plugin@0.2.9-alpha"
+const configuredPlugin = "relay-flow-plugin@0.2.11-alpha"
 
 func TestBuildCommandArgv(t *testing.T) {
 	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")

package/internal/harness/opencode/repo_setup.go

@@ -10,7 +10,7 @@ import (
 	"github.com/rajpopat27/relay-flow/internal/config"
 )
 
-const relayFlowPlugin = "relay-flow-plugin@0.2.9-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.2.11-alpha"
 
 type jsoncToken struct {
 	kind       byte

package/internal/run/detail.go

@@ -0,0 +1,277 @@
+package run
+
+import (
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// StepStatus is the display-only lifecycle of one recorded node visit. It is
+// deliberately separate from State: State is the execution authority's
+// current run state, while StepStatus describes one historical row in the
+// relay-owned inspection projection.
+type StepStatus string
+
+const (
+	StepPending   StepStatus = "pending"
+	StepRunning   StepStatus = "running"
+	StepWaiting   StepStatus = "waiting"
+	StepSucceeded StepStatus = "succeeded"
+	StepFailed    StepStatus = "failed"
+	StepBlocked   StepStatus = "blocked"
+	StepCanceled  StepStatus = "canceled"
+)
+
+// StepEntry is the small, engine-neutral read model used by run inspection.
+// Sequence is the stable execution order within one attempt. A node visit is
+// identified by NodeVisitID when the node is a work node; lifecycle rows such
+// as start/end may not have one.
+type StepEntry struct {
+	RunID          ID            `json:"runId,omitempty"`
+	Sequence       int64         `json:"sequence"`
+	Node           string        `json:"node"`
+	NodeVisitID    NodeVisitID   `json:"nodeVisitId,omitempty"`
+	NodeType       string        `json:"nodeType,omitempty"`
+	ParentSequence int64         `json:"parentSequence,omitempty"`
+	Depth          int           `json:"depth,omitempty"`
+	Status         StepStatus    `json:"status"`
+	StartedAt      *time.Time    `json:"startedAt,omitempty"`
+	FinishedAt     *time.Time    `json:"finishedAt,omitempty"`
+	Duration       time.Duration `json:"duration,omitempty"`
+	DurationKnown  bool          `json:"durationKnown,omitempty"`
+	Message        string        `json:"message,omitempty"`
+	Route          string        `json:"route,omitempty"`
+	Runtime        string        `json:"runtime,omitempty"`
+	Resource       string        `json:"resource,omitempty"`
+}
+
+// RunConditions are derived from the current run state and retry metadata.
+// They are display data only and do not participate in execution decisions.
+type RunConditions struct {
+	NodeRunning    bool `json:"nodeRunning"`
+	Waiting        bool `json:"waiting"`
+	RetryScheduled bool `json:"retryScheduled"`
+	Completed      bool `json:"completed"`
+	Failed         bool `json:"failed"`
+	Canceled       bool `json:"canceled"`
+}
+
+// RunProgress counts reached visits in the derived timeline. Pending rows are
+// the denominator remainder for an active/waiting run.
+type RunProgress struct {
+	Completed int `json:"completed"`
+	Total     int `json:"total"`
+	Pending   int `json:"pending"`
+}
+
+// ResourceDuration is an optional display aggregation. Known is false when
+// executors did not retain resource attribution; zero values with Known=true
+// represent a real zero-duration resource interval.
+type ResourceDuration struct {
+	Known      bool          `json:"known"`
+	Runner     time.Duration `json:"runner,omitempty"`
+	TaskSystem time.Duration `json:"taskSystem,omitempty"`
+	Harness    time.Duration `json:"harness,omitempty"`
+	Other      time.Duration `json:"other,omitempty"`
+}
+
+// RunDetail embeds the original Run value so existing JSON clients that
+// decode a run.Run continue to work when the server adds inspection fields.
+// The remaining fields are read-only relay projection data.
+type RunDetail struct {
+	Run
+	CreatedAt         *time.Time       `json:"createdAt,omitempty"`
+	Conditions        RunConditions    `json:"conditions"`
+	Progress          RunProgress      `json:"progress"`
+	ResourcesDuration ResourceDuration `json:"resourcesDuration"`
+	Steps             []StepEntry      `json:"steps"`
+}
+
+// NewRunDetail creates an empty detail response for a base run. Projection
+// implementations fill Steps and derive the remaining fields.
+func NewRunDetail(r Run) RunDetail {
+	return RunDetail{Run: r, Steps: []StepEntry{}}
+}
+
+// AddPendingNodes adds only pending downstream rows that can be justified by
+// the current run state and selected route. Completed runs intentionally show
+// only actual visits; the static graph is not treated as execution history.
+func (d *RunDetail) AddPendingNodes(wf workflow.Workflow) {
+	if d.State == StateCompleted {
+		return
+	}
+	actual := make(map[string]bool, len(d.Steps))
+	maxSequence := int64(-1)
+	current := d.CurrentNode
+	var currentStep *StepEntry
+	for i := range d.Steps {
+		step := &d.Steps[i]
+		if step.Status == StepPending {
+			continue
+		}
+		actual[step.Node] = true
+		if step.Sequence > maxSequence {
+			maxSequence = step.Sequence
+		}
+		if currentStep == nil || step.Sequence > currentStep.Sequence {
+			currentStep = step
+		}
+	}
+	if current == "" && currentStep != nil {
+		current = currentStep.Node
+	}
+	if current == "" {
+		return
+	}
+
+	candidates := make([]string, 0, 2)
+	addCandidate := func(target string) {
+		if target == "" || actual[target] {
+			return
+		}
+		for _, existing := range candidates {
+			if existing == target {
+				return
+			}
+		}
+		candidates = append(candidates, target)
+	}
+	if currentStep != nil && currentStep.Node == current && currentStep.Route != "" {
+		addCandidate(currentStep.Route)
+	} else if node, ok := wf.Nodes[current]; ok {
+		for _, route := range append(append([]workflow.Route{}, node.OnSuccess...), node.OnFailure...) {
+			addCandidate(route.Target)
+		}
+	}
+
+	added := map[string]bool{}
+	var appendPending func(string, bool)
+	appendPending = func(name string, followSingle bool) {
+		if name == "" || actual[name] || added[name] {
+			return
+		}
+		node, ok := wf.Nodes[name]
+		if !ok {
+			return
+		}
+		added[name] = true
+		nodeType := string(node.Type)
+		if name == workflow.StartNode || name == workflow.EndNode {
+			nodeType = "lifecycle"
+		}
+		maxSequence++
+		d.Steps = append(d.Steps, StepEntry{RunID: d.ID, Sequence: maxSequence,
+			Node: name, NodeType: nodeType, Status: StepPending, Depth: 1})
+		if !followSingle || name == workflow.EndNode {
+			return
+		}
+		routes := append(append([]workflow.Route{}, node.OnSuccess...), node.OnFailure...)
+		if len(routes) == 1 {
+			appendPending(routes[0].Target, true)
+		}
+	}
+	for _, candidate := range candidates {
+		appendPending(candidate, currentStep != nil && currentStep.Node == current && currentStep.Route != "")
+	}
+}
+
+// DeriveInspectionFields fills conditions, progress, and resource durations
+// from the supplied run and step timeline. This helper intentionally reads no
+// executor or task-system state.
+func (d *RunDetail) DeriveInspectionFields(now time.Time) {
+	if now.IsZero() {
+		now = time.Now().UTC()
+	}
+	d.Conditions = RunConditions{
+		NodeRunning:    d.State == StateRunning,
+		Waiting:        d.State == StateWaiting,
+		RetryScheduled: d.Retry != nil,
+		Completed:      d.State == StateCompleted,
+		Failed:         d.State == StateBlocked,
+		Canceled:       d.State == StateCanceled || d.State == StateCanceling,
+	}
+	d.Progress = RunProgress{Total: len(d.Steps)}
+	d.ResourcesDuration = ResourceDuration{}
+	for i, step := range d.Steps {
+		switch step.Status {
+		case StepPending:
+			d.Progress.Pending++
+		default:
+			// Progress counts reached visits, including the current waiting or
+			// blocked visit; pending rows are the denominator remainder.
+			d.Progress.Completed++
+		}
+		duration := step.Duration
+		if duration == 0 && step.StartedAt != nil && step.FinishedAt != nil {
+			duration = step.FinishedAt.Sub(*step.StartedAt)
+			d.Steps[i].DurationKnown = true
+		}
+		if duration == 0 && step.StartedAt != nil && step.FinishedAt == nil &&
+			(step.Status == StepRunning || step.Status == StepWaiting || step.Status == StepBlocked) {
+			duration = now.Sub(*step.StartedAt)
+		}
+		if duration < 0 {
+			duration = 0
+		}
+		if step.Resource != "" {
+			d.ResourcesDuration.Known = true
+		}
+		switch step.Resource {
+		case "runner":
+			d.ResourcesDuration.Runner += duration
+		case "task-system", "taskSystem":
+			d.ResourcesDuration.TaskSystem += duration
+		case "harness":
+			d.ResourcesDuration.Harness += duration
+		case "":
+		default:
+			d.ResourcesDuration.Other += duration
+		}
+	}
+}
+
+// DisplayStatus returns the stable human status vocabulary used by the CLI.
+func (r Run) DisplayStatus() string {
+	switch r.State {
+	case StateCompleted:
+		return "Succeeded"
+	case StateRunning:
+		return "Running"
+	case StateWaiting:
+		return "Waiting"
+	case StateBlocked:
+		return "Failed"
+	case StateCanceled, StateCanceling:
+		return "Canceled"
+	case StateStarting:
+		return "Running"
+	default:
+		return string(r.State)
+	}
+}
+
+// DisplayStatus returns the stable human status vocabulary for a step.
+func (s StepStatus) DisplayStatus() string {
+	switch s {
+	case StepSucceeded:
+		return "Succeeded"
+	case StepRunning:
+		return "Running"
+	case StepWaiting:
+		return "Waiting"
+	case StepFailed, StepBlocked:
+		return "Failed"
+	case StepCanceled:
+		return "Canceled"
+	case StepPending:
+		return "Pending"
+	default:
+		return string(s)
+	}
+}
+
+// IsTerminal reports whether a step has finished and should contribute to
+// progress. It is intentionally local to the display model.
+func (s StepStatus) IsTerminal() bool {
+	return s == StepSucceeded || s == StepFailed || s == StepCanceled
+}

package/internal/run/detail_test.go

@@ -0,0 +1,71 @@
+package run
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+func TestRunDetailDerivationIsRepeatable(t *testing.T) {
+	started := time.Now().UTC().Add(-time.Minute)
+	finished := started.Add(30 * time.Second)
+	detail := NewRunDetail(Run{State: StateWaiting})
+	detail.Steps = []StepEntry{{Status: StepSucceeded, StartedAt: &started, FinishedAt: &finished, Resource: "harness"}}
+	detail.DeriveInspectionFields(time.Now().UTC())
+	first := detail.ResourcesDuration.Harness
+	detail.DeriveInspectionFields(time.Now().UTC())
+	if first <= 0 || detail.ResourcesDuration.Harness != first {
+		t.Fatalf("resource duration changed on repeat: first=%s second=%s", first, detail.ResourcesDuration.Harness)
+	}
+}
+
+func TestCompletedRunDoesNotInventUnvisitedBranchRows(t *testing.T) {
+	detail := NewRunDetail(Run{State: StateCompleted, CurrentNode: workflow.EndNode})
+	detail.Steps = []StepEntry{
+		{Sequence: 0, Node: workflow.StartNode, Status: StepSucceeded},
+		{Sequence: 1, Node: "coding", Status: StepSucceeded},
+		{Sequence: 2, Node: workflow.EndNode, Status: StepSucceeded},
+	}
+	detail.AddPendingNodes(workflow.Workflow{Nodes: map[string]workflow.Node{
+		workflow.StartNode: {}, "coding": {}, "review": {}, workflow.EndNode: {},
+	}})
+	if len(detail.Steps) != 3 {
+		t.Fatalf("completed branch added pending rows: %#v", detail.Steps)
+	}
+}
+
+func TestRunDetailAddsPendingStaticNodesWithoutChangingActualVisits(t *testing.T) {
+	detail := NewRunDetail(Run{State: StateWaiting, CurrentNode: "coding"})
+	detail.Steps = []StepEntry{{Sequence: 0, Node: workflow.StartNode, Status: StepSucceeded, Depth: 1}, {Sequence: 1, Node: "coding", Status: StepWaiting, Depth: 1}}
+	detail.AddPendingNodes(workflow.Workflow{Nodes: map[string]workflow.Node{
+		workflow.StartNode: {}, "coding": {OnSuccess: []workflow.Route{{Target: workflow.EndNode}}}, workflow.EndNode: {}, "review": {},
+	}})
+	detail.DeriveInspectionFields(time.Now().UTC())
+	if len(detail.Steps) != 3 || detail.Steps[2].Status != StepPending || detail.Progress.Pending != 1 || detail.Progress.Total != 3 {
+		t.Fatalf("pending detail = %#v", detail)
+	}
+	if detail.Steps[0].Status != StepSucceeded || detail.Steps[1].Status != StepWaiting {
+		t.Fatalf("actual visits changed: %#v", detail.Steps)
+	}
+}
+
+func TestRunDetailJSONKeepsBaseRunFieldsAndStepIdentity(t *testing.T) {
+	detail := NewRunDetail(Run{ID: "repo/workflow/T-1", State: StateWaiting})
+	detail.Steps = []StepEntry{{RunID: detail.ID, Sequence: 1, Node: "coding", Status: StepWaiting}}
+	raw, err := json.Marshal(detail)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(raw)
+	for _, want := range []string{`"id":"repo/workflow/T-1"`, `"steps"`, `"node":"coding"`} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("JSON %q missing %s", text, want)
+		}
+	}
+	if !strings.Contains(text, `"runId":"repo/workflow/T-1"`) {
+		t.Fatalf("step identity missing from JSON: %s", text)
+	}
+}

package/internal/run/run.go

@@ -124,6 +124,10 @@ type ReportAck struct {
 // its current durable state. Server handlers map it to HTTP 409.
 var ErrRestartConflict = errors.New("restart conflict")
 
+// ErrNotFound identifies a missing durable run in the engine-neutral query
+// boundary. HTTP adapters may map it to their own 404 error type.
+var ErrNotFound = errors.New("run not found")
+
 // NodeRuntimeRegistration binds the OpenCode session emitted for one run/node.
 type NodeRuntimeRegistration struct {
 	RunID     ID     `json:"runId"`

package/internal/server/client.go

@@ -118,6 +118,18 @@ func (c *Client) ListWorkflows(ctx context.Context) ([]*workflow.Workflow, error
 	return out, nil
 }
 
+// ListWorkflowSummaries returns one additive summary row per workflow. The
+// server computes all rows in one query boundary; a server without the
+// optional capability still returns definitions, which are decoded as rows
+// with zero execution counts.
+func (c *Client) ListWorkflowSummaries(ctx context.Context) ([]WorkflowSummary, error) {
+	var out []WorkflowSummary
+	if err := c.call(ctx, http.MethodGet, "/workflows?summary=1", nil, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // GetWorkflow returns one workflow by name.
 func (c *Client) GetWorkflow(ctx context.Context, name string) (*workflow.Workflow, error) {
 	var wf workflow.Workflow
@@ -127,6 +139,15 @@ func (c *Client) GetWorkflow(ctx context.Context, name string) (*workflow.Workfl
 	return &wf, nil
 }
 
+// GetWorkflowDetail returns a definition and a small recent-run summary.
+func (c *Client) GetWorkflowDetail(ctx context.Context, name string) (WorkflowDetail, error) {
+	var out WorkflowDetail
+	if err := c.call(ctx, http.MethodGet, "/workflows/"+url.PathEscape(name)+"?detail=1", nil, &out); err != nil {
+		return WorkflowDetail{}, err
+	}
+	return out, nil
+}
+
 // DiscoverRepos returns runner-visible registration candidates.
 func (c *Client) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, error) {
 	var out []runner.RepoCandidate
@@ -272,6 +293,13 @@ func (c *Client) ListRuns(ctx context.Context, filter run.Filter) ([]run.Run, er
 	if filter.Ticket != "" {
 		q.Set("ticket", filter.Ticket)
 	}
+	if filter.Active != nil {
+		if *filter.Active {
+			q.Set("active", "1")
+		} else {
+			q.Set("active", "0")
+		}
+	}
 	path := "/runs"
 	if s := q.Encode(); s != "" {
 		path += "?" + s
@@ -291,3 +319,14 @@ func (c *Client) GetRunByTicket(ctx context.Context, ticket string) (run.Run, er
 	}
 	return out, nil
 }
+
+// GetRunDetailByTicket returns the additive run inspection response. Existing
+// callers should continue using GetRunByTicket when they only need lifecycle
+// fields.
+func (c *Client) GetRunDetailByTicket(ctx context.Context, ticket string) (run.RunDetail, error) {
+	var out run.RunDetail
+	if err := c.call(ctx, http.MethodGet, "/runs/by-ticket/"+url.PathEscape(ticket), nil, &out); err != nil {
+		return run.RunDetail{}, err
+	}
+	return out, nil
+}