relay-flow 0.3.13-alpha → 0.3.14-alpha

package/cmd/relay-flow/startup_prerequisites_test.go

@@ -0,0 +1,324 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"reflect"
+	"runtime"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/execution/goworkflows"
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	"github.com/rajpopat27/relay-flow/internal/paths"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/server"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// Existing CLI lifecycle tests use production plugin selection with isolated
+// prerequisite dependencies. These fake executables accept only the startup
+// read; neither a desktop runner nor an agent process may be invoked.
+func installHealthyServePrerequisites(t *testing.T, root string) {
+	t.Helper()
+	s := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		user, token, ok := r.BasicAuth()
+		if !ok || user != "startup@example.invalid" || token != "fixture-token" || r.Method != "GET" || r.URL.Path != "/rest/api/3/myself" {
+			t.Errorf("unexpected startup request: %s %s", r.Method, r.URL.Path)
+			http.Error(w, "unexpected request", http.StatusBadRequest)
+			return
+		}
+		_, _ = w.Write([]byte(`{"accountId":"startup-account"}`))
+	}))
+	t.Cleanup(s.Close)
+	credentials := fmt.Sprintf("site: %q\nemail: startup@example.invalid\ntoken: fixture-token\n", s.URL)
+	if err := os.WriteFile(filepath.Join(root, "credentials.yaml"), []byte(credentials), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	bin := t.TempDir()
+	launcher := "orca"
+	if runtime.GOOS == "linux" {
+		launcher = "orca-ide"
+	}
+	for name, script := range map[string]string{
+		launcher:   "#!/bin/sh\n[ \"$*\" = 'repo list --json' ] || exit 99\nprintf '%s' '{\"ok\":true,\"result\":{\"repos\":[]}}'\n",
+		"opencode": "#!/bin/sh\necho 'startup must not execute harness commands' >&2\nexit 99\n",
+	} {
+		if err := os.WriteFile(filepath.Join(bin, name), []byte(script), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("ORCA_CLI_COMMAND", "")
+	t.Setenv("ORCA_DEV_REPO_ROOT", "")
+	t.Setenv("PATH", bin+string(os.PathListSeparator)+os.Getenv("PATH"))
+}
+
+type prerequisiteTask struct{ *scenarioTaskSystem }
+
+func (s *prerequisiteTask) Poll(context.Context) ([]task.Ticket, error) {
+	s.log.add("poll")
+	return nil, nil
+}
+
+type prerequisiteRunner struct {
+	*scenarioRunner
+	probe func(context.Context) error
+}
+
+func (r *prerequisiteRunner) ProbeStartup(ctx context.Context) error {
+	r.log.add("startup:runner")
+	if r.probe != nil {
+		return r.probe(ctx)
+	}
+	return ctx.Err()
+}
+
+type prerequisiteHarness struct {
+	*scenarioHarness
+	probe func(context.Context) error
+}
+
+func (h *prerequisiteHarness) ProbeStartup(ctx context.Context) error {
+	h.log.add("startup:harness")
+	if h.probe != nil {
+		return h.probe(ctx)
+	}
+	return ctx.Err()
+}
+
+var prerequisitePluginSequence atomic.Int64
+
+type prerequisiteFixture struct {
+	paths paths.Paths
+	cfg   *config.Machine
+	log   *scenarioLog
+	rnr   *prerequisiteRunner
+	hrn   *prerequisiteHarness
+}
+
+func newPrerequisiteFixture(t *testing.T, taskProbe func(context.Context) error) *prerequisiteFixture {
+	t.Helper()
+	f := &prerequisiteFixture{paths: pathsForRoot(filepath.Join(t.TempDir(), "relay-flow")), log: newScenarioLog()}
+	t.Setenv("RELAY_FLOW_HOME", f.paths.Root)
+	if err := paths.Ensure(f.paths); err != nil {
+		t.Fatal(err)
+	}
+	name := fmt.Sprintf("prerequisite-test-%d", prerequisitePluginSequence.Add(1))
+	f.cfg = &config.Machine{TaskPlugin: name + "-task", RunnerPlugin: name + "-runner", HarnessPlugin: name + "-harness", PollIntervalSeconds: 1}
+	sys := &prerequisiteTask{newScenarioTaskSystem(f.log)}
+	f.rnr = &prerequisiteRunner{scenarioRunner: newScenarioRunner(f.log)}
+	f.hrn = &prerequisiteHarness{scenarioHarness: newScenarioHarness(f.log)}
+	constructTask := func(context.Context, task.RepoSpec) (task.System, error) {
+		f.log.add("construct:task")
+		return sys, nil
+	}
+	task.Register(f.cfg.TaskPlugin, task.Factory{
+		RequiredRepoKeys: func() []string { return nil },
+		TaskScopeKey:     func(config.RawValues, config.RawValues) (string, error) { return name, nil },
+		New:              constructTask, NewLocal: constructTask,
+		ProbeStartup: func(ctx context.Context, _ config.RawValues, _ map[string]config.Repo) error {
+			f.log.add("startup:task")
+			if taskProbe != nil {
+				return taskProbe(ctx)
+			}
+			return ctx.Err()
+		},
+	})
+	runner.Register(f.cfg.RunnerPlugin, func(config.RawValues) (runner.Runner, error) { return f.rnr, nil })
+	harness.Register(f.cfg.HarnessPlugin, harness.Factory{New: func(config.RawValues) (harness.Harness, error) { return f.hrn, nil }})
+	if err := goworkflows.InitDatabase(f.paths.Database); err != nil {
+		t.Fatal(err)
+	}
+	f.save(t)
+	return f
+}
+
+func (f *prerequisiteFixture) save(t *testing.T) {
+	t.Helper()
+	if err := config.SaveMachine(f.paths.Config, f.cfg); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func (f *prerequisiteFixture) start(t *testing.T) *server.Client {
+	t.Helper()
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan error, 1)
+	go func() { done <- serveRoot(ctx, f.paths, false) }()
+	t.Cleanup(func() {
+		cancel()
+		select {
+		case err := <-done:
+			if err != nil {
+				t.Errorf("serveRoot shutdown: %v", err)
+			}
+		case <-time.After(10 * time.Second):
+			t.Error("serveRoot did not stop")
+		}
+	})
+	client := server.NewClient(f.paths.Socket)
+	waitForServerOrError(t, client, done)
+	return client
+}
+
+func TestServePrerequisitesFailBeforeWorkersPollingRecoveryAndReadiness(t *testing.T) {
+	for _, stage := range []string{"task", "runner", "harness"} {
+		for _, recover := range []bool{false, true} {
+			t.Run(fmt.Sprintf("%s/recover=%v", stage, recover), func(t *testing.T) {
+				failure := errors.New("selected dependency unavailable")
+				var taskProbe func(context.Context) error
+				if stage == "task" {
+					taskProbe = func(context.Context) error { return failure }
+				}
+				f := newPrerequisiteFixture(t, taskProbe)
+				if stage == "runner" {
+					f.rnr.probe = func(context.Context) error { return failure }
+				}
+				if stage == "harness" {
+					f.hrn.probe = func(context.Context) error { return failure }
+				}
+				f.cfg.Repos = map[string]config.Repo{"app": {Path: "/work/app"}}
+				f.save(t)
+				before, err := os.ReadFile(f.paths.Database)
+				if err != nil {
+					t.Fatal(err)
+				}
+				err = serveRoot(context.Background(), f.paths, recover)
+				if !errors.Is(err, failure) || !strings.Contains(err.Error(), stage+" plugin") {
+					t.Fatalf("prerequisite failure = %v", err)
+				}
+				want := []string{"construct:task", "startup:task"}
+				if stage != "task" {
+					want = append(want, "startup:runner")
+				}
+				if stage == "harness" {
+					want = append(want, "startup:harness")
+				}
+				if got := f.log.all(); !reflect.DeepEqual(got, want) {
+					t.Fatalf("unexpected work before prerequisites: %v, want %v", got, want)
+				}
+				after, readErr := os.ReadFile(f.paths.Database)
+				backups, _ := filepath.Glob(f.paths.Database + ".recover-*")
+				if readErr != nil || string(before) != string(after) || len(backups) != 0 {
+					t.Fatalf("prerequisite failure changed execution/recovery state: %v, backups=%v", readErr, backups)
+				}
+				if serverResponding(server.NewClient(f.paths.Socket), 50*time.Millisecond) {
+					t.Fatal("failed prerequisites published readiness")
+				}
+				if _, err := os.Stat(f.paths.Socket); !os.IsNotExist(err) {
+					t.Fatalf("socket created before prerequisites: %v", err)
+				}
+			})
+		}
+	}
+}
+
+func TestServePrerequisitesAcceptZeroReposAndProbeOnlySelectedPlugins(t *testing.T) {
+	f := newPrerequisiteFixture(t, nil)
+	client := f.start(t)
+	repos, err := client.ListRepos(context.Background())
+	if err != nil || len(repos) != 0 {
+		t.Fatalf("zero-repo readiness = %v, %v", repos, err)
+	}
+	if got := f.log.all(); !reflect.DeepEqual(got, []string{"startup:task", "startup:runner", "startup:harness"}) {
+		t.Fatalf("zero-repo startup queried workflows, repos or unselected plugins: %v", got)
+	}
+}
+
+func TestServePrerequisitesDoNotRepeatAcceptedWorkflowPreflightAndIsolateMalformedWorkflow(t *testing.T) {
+	f := newPrerequisiteFixture(t, nil)
+	f.cfg.Repos = map[string]config.Repo{scenarioRepo: {Path: scenarioRepoPath}}
+	f.save(t)
+	store := &workflow.Store{Dir: f.paths.Workflows}
+	if err := store.Put(scenarioWorkflowName, scenarioWorkflowYAML); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(f.paths.Workflows, "broken.yaml"), []byte("name: [broken\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	client := f.start(t)
+	definitions, err := client.ListWorkflows(context.Background())
+	if err != nil || len(definitions) != 2 {
+		t.Fatalf("stored definitions = %v, %v", definitions, err)
+	}
+	for _, definition := range definitions {
+		if definition.Name == scenarioWorkflowName && !definition.IsRoutable() {
+			t.Fatalf("accepted workflow lost routing: %+v", definition)
+		}
+		if definition.Name == "broken" && definition.IsRoutable() {
+			t.Fatal("malformed workflow published routes")
+		}
+	}
+	waitScenario(t, time.Second, func() bool { return f.log.countPrefix("poll") > 0 })
+	for _, stage := range []string{"task", "runner", "harness"} {
+		if f.log.countPrefix("startup:"+stage) != 1 {
+			t.Fatalf("prerequisite repeated per workflow: %v", f.log.all())
+		}
+		assertBefore(t, f.log.all(), "startup:"+stage, "poll")
+	}
+	for _, fullCheck := range []string{"task-config-validated", "runner-repo-validated", "harness-agent-validated", "environment:", "terminal-created:"} {
+		if f.log.countPrefix(fullCheck) != 0 {
+			t.Fatalf("startup repeated full preflight or launched work: %v", f.log.all())
+		}
+	}
+}
+
+func TestPrerequisiteGateUsesTenSecondAggregateAndEarlierCallerBudget(t *testing.T) {
+	start := time.Now()
+	f := newPrerequisiteFixture(t, func(ctx context.Context) error {
+		deadline, ok := ctx.Deadline()
+		if !ok || deadline.After(time.Now().Add(10*time.Second)) {
+			t.Fatalf("missing aggregate ceiling: %v", deadline)
+		}
+		return nil
+	})
+	f.rnr.probe = func(ctx context.Context) error {
+		deadline, ok := ctx.Deadline()
+		if !ok || deadline.After(time.Now().Add(5*time.Second)) {
+			t.Fatalf("missing runner ceiling: %v", deadline)
+		}
+		return nil
+	}
+	if err := checkStartupPrerequisites(context.Background(), f.cfg, f.rnr, f.hrn); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 40*time.Millisecond)
+	defer cancel()
+	f.rnr.probe = func(ctx context.Context) error { <-ctx.Done(); return ctx.Err() }
+	start = time.Now()
+	err := checkStartupPrerequisites(ctx, f.cfg, f.rnr, f.hrn)
+	if !errors.Is(err, context.DeadlineExceeded) || time.Since(start) > time.Second || f.log.countPrefix("startup:harness") != 1 {
+		t.Fatalf("gate extended deadline or continued after failure: %v, %v", err, f.log.all())
+	}
+}
+
+func TestPrerequisiteGateAggregateIncludesMultipleTaskConnectionsAndRunner(t *testing.T) {
+	f := newPrerequisiteFixture(t, func(ctx context.Context) error {
+		// Model two successful task connections, each strictly below five
+		// seconds. The runner must receive the aggregate's remaining budget,
+		// not a fresh five seconds beyond the ten-second prerequisite phase.
+		for i := 0; i < 2; i++ {
+			select {
+			case <-time.After(4 * time.Second):
+			case <-ctx.Done():
+				return ctx.Err()
+			}
+		}
+		return nil
+	})
+	f.rnr.probe = func(ctx context.Context) error { <-ctx.Done(); return ctx.Err() }
+	start := time.Now()
+	err := checkStartupPrerequisites(context.Background(), f.cfg, f.rnr, f.hrn)
+	if !errors.Is(err, context.DeadlineExceeded) || time.Since(start) > 11*time.Second || f.log.countPrefix("startup:harness") != 0 {
+		t.Fatalf("aggregate prerequisite budget not enforced: %v (%v), events=%v", err, time.Since(start), f.log.all())
+	}
+}

package/cmd/relay-flow/startup_readiness_test.go

@@ -0,0 +1,116 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/server"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+func TestServePrerequisitesRequireSelectedPluginProbeSupport(t *testing.T) {
+	for _, stage := range []string{"task", "runner", "harness"} {
+		t.Run(stage, func(t *testing.T) {
+			f := newPrerequisiteFixture(t, nil)
+			if stage == "task" {
+				name := fmt.Sprintf("missing-startup-task-%d", prerequisitePluginSequence.Add(1))
+				task.Register(name, task.Factory{NewLocal: func(context.Context, task.RepoSpec) (task.System, error) {
+					return newScenarioTaskSystem(f.log), nil
+				}})
+				f.cfg.TaskPlugin = name
+			} else if stage == "runner" {
+				name := fmt.Sprintf("missing-startup-runner-%d", prerequisitePluginSequence.Add(1))
+				runner.Register(name, func(config.RawValues) (runner.Runner, error) {
+					// Embedding the runtime interface deliberately does not expose
+					// the separate startup boundary of the concrete fake.
+					return struct{ runner.Runner }{f.rnr}, nil
+				})
+				f.cfg.RunnerPlugin = name
+			} else {
+				name := fmt.Sprintf("missing-startup-harness-%d", prerequisitePluginSequence.Add(1))
+				harness.Register(name, harness.Factory{New: func(config.RawValues) (harness.Harness, error) {
+					return struct{ harness.Harness }{f.hrn}, nil
+				}})
+				f.cfg.HarnessPlugin = name
+			}
+			f.save(t)
+			err := serveRoot(context.Background(), f.paths, false)
+			if err == nil || !strings.Contains(err.Error(), stage+" plugin") || !strings.Contains(err.Error(), "startup prob") {
+				t.Fatalf("selected dependency was silently skipped: %v", err)
+			}
+			if serverResponding(server.NewClient(f.paths.Socket), 50*time.Millisecond) {
+				t.Fatal("unsupported probe published readiness")
+			}
+		})
+	}
+}
+
+func TestForegroundAndDetachedServeNeverReportReadinessOnDependencyFailure(t *testing.T) {
+	binary := buildCLIBinary(t)
+	for _, stage := range []string{"task", "runner", "harness"} {
+		for _, foreground := range []bool{false, true} {
+			t.Run(fmt.Sprintf("%s/foreground=%v", stage, foreground), func(t *testing.T) {
+				root := filepath.Join(t.TempDir(), "relay-flow")
+				t.Setenv("RELAY_FLOW_HOME", root)
+				init := exec.Command(binary, initArgs()...)
+				init.Env = os.Environ()
+				if out, err := init.CombinedOutput(); err != nil {
+					t.Fatalf("init: %v\n%s", err, out)
+				}
+				installHealthyServePrerequisites(t, root)
+				bin := strings.Split(os.Getenv("PATH"), string(os.PathListSeparator))[0]
+				// The child's own environment has only the isolated executables.
+				// Removing one must not resolve a real installed dependency.
+				t.Setenv("PATH", bin)
+				missing := filepath.Join(root, "credentials.yaml")
+				if stage == "runner" {
+					launcher := "orca"
+					if runtime.GOOS == "linux" {
+						launcher = "orca-ide"
+					}
+					missing = filepath.Join(bin, launcher)
+				} else if stage == "harness" {
+					missing = filepath.Join(bin, "opencode")
+				}
+				if err := os.Remove(missing); err != nil {
+					t.Fatal(err)
+				}
+				args := []string{"serve"}
+				if foreground {
+					args = append(args, "--foreground")
+				}
+				ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+				defer cancel()
+				serve := exec.CommandContext(ctx, binary, args...)
+				serve.Env = os.Environ()
+				out, err := serve.CombinedOutput()
+				if err == nil || strings.Contains(string(out), "server started") {
+					t.Fatalf("failed dependency reported readiness: err=%v, output=%s", err, out)
+				}
+				log := readFile(t, filepath.Join(root, "server.log"))
+				if !strings.Contains(log, "startup prerequisite "+stage+" plugin") {
+					t.Fatalf("server did not report the selected dependency: %s", log)
+				}
+				if !strings.Contains(string(out), "startup prerequisite "+stage+" plugin") {
+					t.Fatalf("startup failure lost dependency identity: %s", out)
+				}
+				if !strings.Contains(string(out), filepath.Join(root, "server.log")) {
+					t.Fatalf("startup failure lost log location: %s", out)
+				}
+				if serverResponding(server.NewClient(filepath.Join(root, "server.sock")), 50*time.Millisecond) {
+					t.Fatal("failed dependency left a ready server")
+				}
+			})
+		}
+	}
+}

package/cmd/relay-flow/startup_submission_test.go

@@ -0,0 +1,123 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+type rejectingSubmissionTask struct {
+	*scenarioTaskSystem
+	failure error
+}
+
+func (s *rejectingSubmissionTask) ValidateConfig(ctx context.Context, root config.RawValues, nodes map[string]config.RawValues) error {
+	if s.failure != nil {
+		return s.failure
+	}
+	return s.scenarioTaskSystem.ValidateConfig(ctx, root, nodes)
+}
+
+type rejectingSubmissionRunner struct {
+	*scenarioRunner
+	failure error
+}
+
+func (r *rejectingSubmissionRunner) ValidateRepo(ctx context.Context, name, path string) error {
+	if r.failure != nil {
+		return r.failure
+	}
+	return r.scenarioRunner.ValidateRepo(ctx, name, path)
+}
+
+type rejectingSubmissionHarness struct {
+	*scenarioHarness
+	failure error
+}
+
+func (h *rejectingSubmissionHarness) ValidateAgent(ctx context.Context, path, agent string) error {
+	if h.failure != nil {
+		return h.failure
+	}
+	return h.scenarioHarness.ValidateAgent(ctx, path, agent)
+}
+
+type submissionActiveRuns struct{}
+
+func (submissionActiveRuns) HasActiveWorkflow(context.Context, string) (bool, error) {
+	return false, nil
+}
+
+func TestStartupPrerequisitesDoNotBypassSubmissionValidationOrReplaceAcceptedState(t *testing.T) {
+	for _, stage := range []string{"task-config", "runner-repo", "harness-agent"} {
+		t.Run(stage, func(t *testing.T) {
+			f := newPrerequisiteFixture(t, nil)
+			sys := &rejectingSubmissionTask{scenarioTaskSystem: newScenarioTaskSystem(f.log)}
+			rnr := &rejectingSubmissionRunner{scenarioRunner: newScenarioRunner(f.log)}
+			hrn := &rejectingSubmissionHarness{scenarioHarness: newScenarioHarness(f.log)}
+			registry := repo.NewRegistry()
+			registered := &repo.Repo{Name: scenarioRepo, Path: scenarioRepoPath, TaskSystem: sys}
+			registry.Replace(registered)
+			store := &workflow.Store{Dir: f.paths.Workflows}
+			service := workflow.NewService(store, submissionActiveRuns{}, repoExists{registry})
+			service.ValidateTaskConfig = workflowConfigValidator(registry)
+			service.ValidateSubmission = workflowSubmissionValidator(registry, rnr, hrn)
+			service.Rebind = func() error { return registry.BindWorkflows(service.Registry().List()) }
+			accepted, err := service.Submit(context.Background(), scenarioWorkflowYAML)
+			if err != nil {
+				t.Fatal(err)
+			}
+			bindings := registered.Bindings()
+			yamlPath := filepath.Join(store.Dir, scenarioWorkflowName+".yaml")
+			hashPath := filepath.Join(store.Dir, scenarioWorkflowName+".sha256")
+			beforeYAML := readFile(t, yamlPath)
+			beforeHash := readFile(t, hashPath)
+			failure := errors.New("candidate-specific validation rejected")
+			switch stage {
+			case "task-config":
+				sys.failure = failure
+			case "runner-repo":
+				rnr.failure = failure
+			case "harness-agent":
+				hrn.failure = failure
+			}
+			// Basic machine health still succeeds; it does not authorize a
+			// candidate that fails the full repo/task/agent validation path.
+			if err := checkStartupPrerequisites(context.Background(), f.cfg, rnr, hrn); err != nil {
+				t.Fatal(err)
+			}
+			candidate := []byte(strings.Replace(string(scenarioWorkflowYAML), "Implement the requested change.", "Rejected replacement description.", 1))
+			if _, err := service.Submit(context.Background(), candidate); !errors.Is(err, failure) {
+				t.Fatalf("submission bypassed %s validation: %v", stage, err)
+			}
+			if readFile(t, yamlPath) != beforeYAML || readFile(t, hashPath) != beforeHash {
+				t.Fatal("failed submission replaced accepted YAML/hash")
+			}
+			current, err := service.Get(scenarioWorkflowName)
+			if err != nil || current != accepted || !current.IsRoutable() {
+				t.Fatalf("failed submission replaced accepted in-memory definition: %v", err)
+			}
+			after := registered.Bindings()
+			if len(bindings) != 1 || len(after) != 1 || after[0].Workflow != bindings[0].Workflow || after[0].Workflow != accepted {
+				t.Fatal("failed submission changed routing bindings")
+			}
+			if matches := after[0].Match(task.Ticket{Key: scenarioTicket}); !matches {
+				t.Fatal("accepted routing matcher no longer works")
+			}
+			if transactions, err := filepath.Glob(filepath.Join(store.Dir, "*.txn")); err != nil || len(transactions) != 0 {
+				t.Fatalf("failed validation attempted publication: %v, %v", transactions, err)
+			}
+			if _, err := os.Stat(yamlPath); err != nil {
+				t.Fatal(err)
+			}
+		})
+	}
+}

package/internal/harness/opencode/opencode.go

@@ -102,6 +102,20 @@ func New(cfg ...Config) *Harness {
 	}}
 }
 
+var _ harness.StartupProber = (*Harness)(nil)
+
+// ProbeStartup resolves only the OpenCode executable, without agent listing,
+// repository/template inspection or session launches.
+func (*Harness) ProbeStartup(ctx context.Context) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if _, err := exec.LookPath("opencode"); err != nil {
+		return fmt.Errorf("opencode startup: required executable \"opencode\" unavailable: %w", err)
+	}
+	return nil
+}
+
 // SetupRepo ensures the relay-flow runtime plugin is configured for OpenCode
 // in the registered repository.
 func (h *Harness) SetupRepo(_ context.Context, repoPath string) error {

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.3.13-alpha"
+const configuredPlugin = "relay-flow-plugin@0.3.14-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.3.13-alpha"
+const relayFlowPlugin = "relay-flow-plugin@0.3.14-alpha"
 
 type jsoncToken struct {
 	kind       byte

package/internal/harness/pi/pi.go

@@ -96,6 +96,20 @@ func New(cfg ...Config) *Harness {
 	}}
 }
 
+var _ harness.StartupProber = (*Harness)(nil)
+
+// ProbeStartup resolves only the Pi executable; agent/template validation is
+// deliberately separate and no session is launched.
+func (*Harness) ProbeStartup(ctx context.Context) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if _, err := exec.LookPath("pi"); err != nil {
+		return fmt.Errorf("pi startup: required executable \"pi\" unavailable: %w", err)
+	}
+	return nil
+}
+
 // SetupRepo is intentionally a no-op. The relay-flow Pi runtime extension is
 // installed manually in Pi's global package settings rather than configured
 // in each repository.

package/internal/harness/startup.go

@@ -0,0 +1,25 @@
+package harness
+
+import (
+	"context"
+	"fmt"
+	"time"
+)
+
+// StartupProber is the local selected-executable prerequisite boundary. It
+// must not enumerate agents, inspect repositories or launch a session.
+type StartupProber interface {
+	ProbeStartup(context.Context) error
+}
+
+// ProbeStartup checks the constructed selected harness. Missing support is
+// an error, not permission to skip its executable prerequisite.
+func ProbeStartup(ctx context.Context, selected Harness) error {
+	probe, ok := selected.(StartupProber)
+	if !ok {
+		return fmt.Errorf("selected harness does not implement startup probing")
+	}
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	return probe.ProbeStartup(ctx)
+}