relay-flow 0.3.13-alpha → 0.3.14-alpha

package/README.md

@@ -28,13 +28,13 @@ same `relay-flow-plugin` package with host-specific entrypoints.
 **OpenCode**
 
 ```sh
-opencode plugin relay-flow-plugin@0.3.13-alpha
+opencode plugin relay-flow-plugin@0.3.14-alpha
 ```
 
 **Pi**
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.13-alpha
+pi install npm:relay-flow-plugin@0.3.14-alpha
 ```
 
 Pi loads the package's `pi.ts` extension from its manifest. Do not add
@@ -155,6 +155,15 @@ and app; Herdr requires its CLI/server. OpenCode and Pi each require their
 corresponding agent runtime. These integrations remain behind their small
 contracts, so task-system fields do not leak into runners or harnesses.
 
+The Orca adapter selects its launcher once in the **server's** environment:
+`ORCA_CLI_COMMAND` when set, otherwise `orca-dev` when
+`ORCA_DEV_REPO_ROOT` is set, otherwise `orca-ide` on Linux and `orca` on
+macOS. The resolved executable is reused for every adapter operation; no
+alternate binary, shell alias, or legacy shim is tried on failure. On Linux,
+substitute `orca-ide` for `orca` in the standalone setup examples below (or
+use the explicit session selector). Changing the client's PATH does not
+change an already-running server's launcher.
+
 ## Detailed setup
 
 ### Harness configuration
@@ -164,7 +173,7 @@ OpenCode plugin configuration uses both entrypoints. The server entrypoint is li
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["relay-flow-plugin@0.3.13-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.14-alpha"]
 }
 ```
 
@@ -173,7 +182,7 @@ The native HITL approval entrypoint is listed in `.opencode/tui.json`:
 ```json
 {
   "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["relay-flow-plugin@0.3.13-alpha"]
+  "plugin": ["relay-flow-plugin@0.3.14-alpha"]
 }
 ```
 
@@ -189,7 +198,7 @@ Pi plugin: install the same published package manually in Pi's global package
 settings before starting a Pi harness session:
 
 ```sh
-pi install npm:relay-flow-plugin@0.3.13-alpha
+pi install npm:relay-flow-plugin@0.3.14-alpha
 ```
 
 Relay-flow does not install or configure the package automatically. Pi resolves
@@ -418,6 +427,31 @@ codes, and server lifecycle. Detached startup logs diagnostics to
 working directory. Use `--foreground` only when the process supervisor owns
 the server lifetime; `--background` remains accepted for existing scripts.
 
+Before workers, pollers, recovery effects, or socket readiness, `serve` checks
+only basic prerequisites for the selected task system, runner runtime, and
+local harness executable. This phase has a ten-second aggregate deadline and
+at most five seconds per external probe, with no startup retries. These budgets
+do not cover database opening or durable replay. Zero registered repositories
+is valid: empty Orca/Herdr runtimes are healthy; Beads checks local `bd` and
+reports connection verification deferred to registration only when no workspace
+is explicitly configured. Shared configured Beads workspaces are probed once.
+Full repository, workflow, task-setting, and agent validation remains at
+registration/submission, not a repeated startup preflight. Changed, malformed,
+or missing-hash stored workflows remain isolated from routing while the
+management API and unrelated accepted workflows stay available when basic
+prerequisites pass.
+
+Prerequisite errors distinguish missing executable, executable launch failure,
+authentication/permission rejection, connection failure, malformed response,
+and timeout. Foreground and detached failures exit nonzero without `server
+started`, identify the selected dependency and safe operation, and point to
+`server.log`. Detached diagnostics read only the current child's bounded
+startup-failure record; old or unrelated log entries are not replayed. Startup
+never installs/starts dependencies, enumerates agents, scans ticket history,
+or changes the child environment to hide a failure. Guided registration
+propagates startup errors and reuses an existing ready server without assuming
+that executable resolution in the client changes the server's environment.
+
 `serve --recover` treats ALL SQLite execution state as gone, closes surviving run-owned terminals (preserving worktrees and code), resets Jira parent+mailbox state, and starts every labeled parent in a fresh deterministic run from `start` with fresh `nodeVisitID`s. Recovery never runs automatically; database loss is never inferred.
 
 ---

package/cmd/relay-flow/commands_test.go

@@ -177,6 +177,7 @@ func TestTaskAuthDispatchesSelectedPlugin(t *testing.T) {
 func TestServerLockIsOwnerOnly(t *testing.T) {
 	home := t.TempDir()
 	initHome(t, home)
+	installHealthyServePrerequisites(t, filepath.Join(home, ".relay-flow"))
 	// Start foreground serve in the background of the test via the parser
 	// entry; it creates the flock file then blocks. We assert the lock file's
 	// mode, then stop the fixture so the test does not leak a server.
@@ -216,6 +217,7 @@ func TestServerLockIsOwnerOnly(t *testing.T) {
 func TestServerSocketIsOwnerOnly(t *testing.T) {
 	home := t.TempDir()
 	initHome(t, home)
+	installHealthyServePrerequisites(t, filepath.Join(home, ".relay-flow"))
 	done := make(chan int, 1)
 	go func() { done <- cli(t, home, "", "serve", "--foreground") }()
 	t.Cleanup(func() {
@@ -1133,6 +1135,7 @@ func TestDefaultServeRelativeHomeUsesSharedState(t *testing.T) {
 	if out, err := init.CombinedOutput(); err != nil {
 		t.Fatalf("relative-home init: %v\n%s", err, out)
 	}
+	installHealthyServePrerequisites(t, expectedRoot)
 	for _, name := range []string{"config.yaml", "state.db"} {
 		if _, err := os.Stat(filepath.Join(expectedRoot, name)); err != nil {
 			t.Fatalf("relative-home init missing %s: %v", name, err)
@@ -1164,6 +1167,7 @@ func TestDefaultServeRelativeHomeUsesSharedState(t *testing.T) {
 func TestInProcessDefaultServeReadinessAndStop(t *testing.T) {
 	home := t.TempDir()
 	initHome(t, home)
+	installHealthyServePrerequisites(t, filepath.Join(home, ".relay-flow"))
 	if code := cli(t, home, "", "serve"); code != exitOK {
 		t.Fatalf("in-process detached serve exit = %d", code)
 	}
@@ -1184,6 +1188,7 @@ func TestDetachedServeUsesStableWorkingDirectory(t *testing.T) {
 	if code := run(initArgs(), strings.NewReader("")); code != 0 {
 		t.Fatalf("init exit = %d", code)
 	}
+	installHealthyServePrerequisites(t, root)
 	binary := buildCLIBinary(t)
 	t.Cleanup(func() {
 		stop := exec.Command(binary, "stop")
@@ -1230,6 +1235,7 @@ func TestForegroundServeUsesStableWorkingDirectory(t *testing.T) {
 	if code := run(initArgs(), strings.NewReader("")); code != 0 {
 		t.Fatalf("init exit = %d", code)
 	}
+	installHealthyServePrerequisites(t, root)
 	binary := buildCLIBinary(t)
 	caller := t.TempDir()
 	serve := exec.Command(binary, "serve", "--foreground")
@@ -1288,6 +1294,7 @@ func TestForegroundServeRelativeHomeUsesSharedState(t *testing.T) {
 	if out, err := init.CombinedOutput(); err != nil {
 		t.Fatalf("relative-home init: %v\n%s", err, out)
 	}
+	installHealthyServePrerequisites(t, expectedRoot)
 	serve := exec.Command(binary, "serve", "--foreground")
 	serve.Dir = caller
 	serve.Env = os.Environ()
@@ -1349,6 +1356,7 @@ func testDetachedServe(t *testing.T, mode []string) {
 	if code := run(initArgs(), strings.NewReader("")); code != 0 {
 		t.Fatalf("init exit = %d", code)
 	}
+	installHealthyServePrerequisites(t, root)
 	binary := buildCLIBinary(t)
 	args := append([]string{"serve"}, mode...)
 	start := exec.Command(binary, args...)
@@ -1455,6 +1463,7 @@ func TestForegroundServeRemainsBlocking(t *testing.T) {
 	if code := run(initArgs(), strings.NewReader("")); code != 0 {
 		t.Fatalf("init exit = %d", code)
 	}
+	installHealthyServePrerequisites(t, root)
 	binary := buildCLIBinary(t)
 	serve := exec.Command(binary, "serve", "--foreground")
 	serve.Env = os.Environ()

package/cmd/relay-flow/main.go

@@ -13,7 +13,6 @@ import (
 	"flag"
 	"fmt"
 	"io"
-	"log/slog"
 	"os"
 	"os/exec"
 	"os/signal"
@@ -896,8 +895,8 @@ func cmdServe(p paths.Paths, args []string) int {
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 	if err := serveRoot(ctx, p, *recover); err != nil {
-		slog.Error("server startup failed", "error", err)
-		fmt.Fprintln(os.Stderr, err)
+		logStartupFailure(err)
+		fmt.Fprintf(os.Stderr, "%s; see %s\n", startupDiagnostic(err.Error()), p.ServerLog)
 		return exitFail
 	}
 	return exitOK
@@ -928,6 +927,8 @@ func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 		testServeCancel chan struct{}
 		observedOwner   = lockHeld
 		devNull         *os.File
+		logOffset       = startupLogOffset(p.ServerLog)
+		childPID        = os.Getpid()
 	)
 	if !lockHeld {
 		wait = make(chan error, 1)
@@ -949,7 +950,11 @@ func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 					return
 				}
 				defer logCloser.Close()
-				wait <- serveRoot(serveCtx, p, recover)
+				serveErr := serveRoot(serveCtx, p, recover)
+				if serveErr != nil {
+					logStartupFailure(serveErr)
+				}
+				wait <- serveErr
 			}()
 		} else {
 			executable, resolveErr := os.Executable()
@@ -972,6 +977,7 @@ func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 			if err := cmd.Start(); err != nil {
 				return fmt.Errorf("serve --background: start: %w; see %s", err, p.ServerLog)
 			}
+			childPID = cmd.Process.Pid
 			go func() { wait <- cmd.Wait() }()
 		}
 	}
@@ -1017,6 +1023,9 @@ func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 				cmd = nil
 				continue
 			}
+			if diagnostic := readStartupFailure(p.ServerLog, logOffset, childPID); diagnostic != "" {
+				return fmt.Errorf("serve --background: %s; server exited before readiness: %v; see %s", diagnostic, childErr, p.ServerLog)
+			}
 			return fmt.Errorf("serve --background: server exited before readiness: %v; see %s", childErr, p.ServerLog)
 		case <-ticker.C:
 		}
@@ -1433,8 +1442,8 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 	return exitOK
 }
 
-func repoMultiSelect(options []huh.Option[int], selected *[]int) *huh.MultiSelect[int] {
-	return huh.NewMultiSelect[int]().
+func repoMultiSelect(options []huh.Option[int], selected *[]int) *repoMultiSelectField {
+	return &repoMultiSelectField{huh.NewMultiSelect[int]().
 		Title("Select repositories").
 		Description("Press / to filter repositories; select [+] Add repository to add a runner resource.").
 		Filterable(true).
@@ -1445,7 +1454,7 @@ func repoMultiSelect(options []huh.Option[int], selected *[]int) *huh.MultiSelec
 				return fmt.Errorf("select at least one repository")
 			}
 			return nil
-		})
+		})}
 }
 
 // kvFlags collects repeated key=value flags (registration task config).

package/cmd/relay-flow/repo_registration.go

@@ -4,8 +4,10 @@ import (
 	"context"
 	"fmt"
 	"path/filepath"
+	"slices"
 	"strings"
 
+	tea "github.com/charmbracelet/bubbletea"
 	"github.com/charmbracelet/huh"
 	"github.com/rajpopat27/relay-flow/internal/config"
 	"github.com/rajpopat27/relay-flow/internal/repo"
@@ -16,6 +18,72 @@ import (
 
 const addRepositorySelection = -1
 
+// repoMultiSelectField keeps Huh's picker behavior, except that bulk selection
+// toggles only visible repositories, never the explicit Add action.
+type repoMultiSelectField struct {
+	*huh.MultiSelect[int]
+}
+
+func (m *repoMultiSelectField) WithKeyMap(keymap *huh.KeyMap) huh.Field {
+	copy := *keymap
+	copy.MultiSelect.SelectAll.SetHelp("ctrl+a", "toggle repositories")
+	copy.MultiSelect.SelectNone.SetHelp("ctrl+a", "toggle repositories")
+	m.MultiSelect.WithKeyMap(&copy)
+	return m
+}
+
+func (m *repoMultiSelectField) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	if key, ok := msg.(tea.KeyMsg); ok && key.Type == tea.KeyCtrlA {
+		m.toggleRepositories()
+		return m, nil
+	}
+	_, cmd := m.MultiSelect.Update(msg)
+	return m, cmd
+}
+
+func (m *repoMultiSelectField) toggleRepositories() {
+	original, ok := m.Hovered()
+	if !ok {
+		return
+	}
+	// Use Huh's own filtered view and Space handling rather than maintaining
+	// a second filter or selection state. Temporarily stop editing the filter
+	// so navigation/toggle keys do not modify its text.
+	filtering := m.GetFiltering()
+	m.Filtering(false)
+	defer m.Filtering(filtering)
+	m.MultiSelect.Update(tea.KeyMsg{Type: tea.KeyHome})
+	selected := m.GetValue().([]int)
+	visible := []int{}
+	allSelected := true
+	for {
+		value, ok := m.Hovered()
+		if !ok || (len(visible) > 0 && visible[len(visible)-1] == value) {
+			break
+		}
+		visible = append(visible, value)
+		if value != addRepositorySelection && !slices.Contains(selected, value) {
+			allSelected = false
+		}
+		m.MultiSelect.Update(tea.KeyMsg{Type: tea.KeyDown})
+	}
+	m.MultiSelect.Update(tea.KeyMsg{Type: tea.KeyHome})
+	for _, value := range visible {
+		if value != addRepositorySelection && slices.Contains(selected, value) == allSelected {
+			m.MultiSelect.Update(tea.KeyMsg{Type: tea.KeySpace})
+		}
+		m.MultiSelect.Update(tea.KeyMsg{Type: tea.KeyDown})
+	}
+	// Restore the hovered entry so Space still acts on the same option.
+	m.MultiSelect.Update(tea.KeyMsg{Type: tea.KeyHome})
+	for _, value := range visible {
+		if value == original {
+			break
+		}
+		m.MultiSelect.Update(tea.KeyMsg{Type: tea.KeyDown})
+	}
+}
+
 func repoSelectionOptions(candidates []runner.RepoCandidate) []huh.Option[int] {
 	options := make([]huh.Option[int], 0, len(candidates)+1)
 	for i, candidate := range candidates {

package/cmd/relay-flow/repo_selection_keyboard_test.go

@@ -0,0 +1,178 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/huh"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/server"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+func repoKeyboardField(candidates []runner.RepoCandidate, selected *[]int) huh.Field {
+	field := repoMultiSelect(repoSelectionOptions(candidates), selected)
+	// Apply the same setup that Huh's form/group applies to a field.
+	huh.NewForm(huh.NewGroup(field))
+	field.Focus()
+	return field
+}
+
+func sendRepoKeys(t *testing.T, field huh.Field, keys ...tea.KeyMsg) {
+	t.Helper()
+	for _, key := range keys {
+		model, _ := field.Update(key)
+		if model != field {
+			t.Fatal("keyboard update replaced the production selection field")
+		}
+	}
+}
+
+func TestRepoSelectionFormCtrlAEnter(t *testing.T) {
+	var selected []int
+	field := repoMultiSelect(repoSelectionOptions([]runner.RepoCandidate{
+		{Name: "payments", Path: "/work/payments"},
+		{Name: "checkout", Path: "/work/checkout"},
+	}), &selected)
+	form := huh.NewForm(huh.NewGroup(field)).
+		WithProgramOptions(tea.WithoutRenderer(), tea.WithoutSignalHandler()).
+		WithInput(strings.NewReader("\x01\r")).
+		WithOutput(io.Discard).
+		WithTimeout(3 * time.Second)
+	if err := form.Run(); err != nil {
+		t.Fatal(err)
+	}
+	if form.State != huh.StateCompleted || fmt.Sprint(selected) != "[0 1]" {
+		t.Fatalf("Ctrl+A/Enter: form state=%v selected=%v", form.State, selected)
+	}
+}
+
+func TestRepoSelectionKeyboardBulkToggle(t *testing.T) {
+	candidates := []runner.RepoCandidate{
+		{Name: "payments", Path: "/work/payments"},
+		{Name: "checkout", Path: "/work/checkout"},
+	}
+	for _, count := range []int{0, 1, 2} {
+		t.Run(fmt.Sprintf("%d repositories", count), func(t *testing.T) {
+			var selected []int
+			field := repoKeyboardField(candidates[:count], &selected)
+			all := make([]int, count)
+			for i := range all {
+				all[i] = i
+			}
+			for _, want := range []string{fmt.Sprint(all), "[]"} {
+				sendRepoKeys(t, field, tea.KeyMsg{Type: tea.KeyCtrlA})
+				if fmt.Sprint(selected) != want {
+					t.Fatalf("Ctrl+A selected %v, want %s (Add must never be bulk-selected)", selected, want)
+				}
+			}
+			sendRepoKeys(t, field, tea.KeyMsg{Type: tea.KeyEnter})
+			if field.Error() == nil {
+				t.Fatal("Enter accepted an empty repository selection")
+			}
+			// Explicit Space on Add remains available even without candidates.
+			sendRepoKeys(t, field, tea.KeyMsg{Type: tea.KeyEnd}, tea.KeyMsg{Type: tea.KeySpace}, tea.KeyMsg{Type: tea.KeyEnter})
+			if field.Error() != nil || fmt.Sprint(selected) != "[-1]" {
+				t.Fatalf("explicit Add: selected=%v error=%v", selected, field.Error())
+			}
+		})
+	}
+}
+
+func TestRepoSelectionKeyboardFilteredBulkToggle(t *testing.T) {
+	candidates := []runner.RepoCandidate{
+		{Name: "payments", Path: "/work/payments"},
+		{Name: "checkout", Path: "/work/checkout"},
+		{Name: "payments-api", Path: "/work/payments-api"},
+	}
+	for _, filter := range []string{"", "payments", "repository", "does-not-match"} {
+		for _, editing := range []bool{false, true} {
+			t.Run(fmt.Sprintf("filter=%s/editing=%t", filter, editing), func(t *testing.T) {
+				selected := []int{1} // A selection outside the payments filter must survive.
+				field := repoKeyboardField(candidates, &selected)
+				sendRepoKeys(t, field, tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune{'/'}}, tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune(filter)})
+				if !editing {
+					sendRepoKeys(t, field, tea.KeyMsg{Type: tea.KeyEnter})
+				}
+				wants := []string{"[1]", "[1]"}
+				switch filter {
+				case "":
+					wants = []string{"[0 1 2]", "[]"}
+				case "payments":
+					wants = []string{"[0 1 2]", "[1]"}
+				case "does-not-match":
+					if !editing {
+						// Huh clears a no-match filter when Enter commits it.
+						wants = []string{"[0 1 2]", "[]"}
+					}
+				}
+				for _, want := range wants {
+					sendRepoKeys(t, field, tea.KeyMsg{Type: tea.KeyCtrlA})
+					if fmt.Sprint(selected) != want {
+						t.Fatalf("Ctrl+A selected %v, want %s", selected, want)
+					}
+				}
+			})
+		}
+	}
+}
+
+func TestRepoSelectionKeyboardBulkProceedsWithoutAdding(t *testing.T) {
+	for _, count := range []int{1, 2} {
+		t.Run(fmt.Sprintf("%d repositories", count), func(t *testing.T) {
+			home := t.TempDir()
+			deps := serveRegister(t, home, []string{"project", "component"})
+			deps.candidates = []runner.RepoCandidate{
+				{Name: "payments", Path: "/work/payments"},
+				{Name: "checkout", Path: "/work/checkout"},
+			}[:count]
+			client := server.NewClient(filepath.Join(home, ".relay-flow", "server.sock"))
+			candidates, selected, err := selectReposInteractiveWithPrompts(context.Background(), client, deps.candidates, nil,
+				func(candidates []runner.RepoCandidate, selected []int) ([]int, error) {
+					field := repoKeyboardField(candidates, &selected)
+					sendRepoKeys(t, field, tea.KeyMsg{Type: tea.KeyCtrlA}, tea.KeyMsg{Type: tea.KeyEnter})
+					return selected, field.Error()
+				},
+				func() (runner.RepoCandidate, error) {
+					t.Fatal("Ctrl+A/Enter opened the path/name prompt")
+					return runner.RepoCandidate{}, nil
+				})
+			if err != nil {
+				t.Fatal(err)
+			}
+			registration := task.Registration{Fields: []task.RegistrationField{
+				{Key: "project", Title: "Project"},
+				{Key: "component", Title: "Component", Derived: true},
+			}}
+			if err := registerSelectedReposDynamic(context.Background(), client, candidates, selected, registration, kvFlags{"project": "PAY"}); err != nil {
+				t.Fatal(err)
+			}
+			if len(deps.ensureCalls) != 0 || len(deps.successful) != count {
+				t.Fatalf("ensure calls=%v registrations=%v", deps.ensureCalls, deps.successful)
+			}
+			for _, input := range deps.successful {
+				if input.TaskConfig["project"] != "PAY" || input.TaskConfig["component"] != input.Name {
+					t.Fatalf("incorrect shared mapping: %+v", input)
+				}
+			}
+		})
+	}
+}
+
+func TestRepoSelectionKeyboardSpacePreservesExplicitAdd(t *testing.T) {
+	selected := []int{0}
+	field := repoKeyboardField([]runner.RepoCandidate{{Name: "payments", Path: "/work/payments"}}, &selected)
+	sendRepoKeys(t, field, tea.KeyMsg{Type: tea.KeyEnd}, tea.KeyMsg{Type: tea.KeySpace}, tea.KeyMsg{Type: tea.KeyCtrlA}, tea.KeyMsg{Type: tea.KeyEnter})
+	if fmt.Sprint(selected) != "[-1]" || field.Error() != nil {
+		t.Fatalf("explicit Add was lost: selected=%v error=%v", selected, field.Error())
+	}
+	if !strings.Contains(field.View(), "Add repository") {
+		t.Fatal("Add action is no longer visible")
+	}
+}

package/cmd/relay-flow/scenario_test.go

@@ -60,6 +60,16 @@ func init() {
 		},
 		New:      newScenarioTask,
 		NewLocal: newScenarioTask,
+		ProbeStartup: func(ctx context.Context, _ config.RawValues, _ map[string]config.Repo) error {
+			scenarioFactoryMu.Lock()
+			system := scenarioFactorySystem
+			scenarioFactoryMu.Unlock()
+			probe, ok := system.(interface{ ProbeStartup(context.Context) error })
+			if !ok {
+				return errors.New("scenario task system has no startup probe")
+			}
+			return probe.ProbeStartup(ctx)
+		},
 	})
 	runner.Register(scenarioRunnerPlugin, func(config.RawValues) (runner.Runner, error) {
 		scenarioFactoryMu.Lock()
@@ -817,6 +827,11 @@ func newScenarioTaskSystem(log *scenarioLog) *scenarioTaskSystem {
 	}
 }
 
+func (s *scenarioTaskSystem) ProbeStartup(ctx context.Context) error {
+	s.log.add("startup:task")
+	return ctx.Err()
+}
+
 func (s *scenarioTaskSystem) Poll(context.Context) ([]task.Ticket, error) {
 	s.log.add("poll")
 	s.mu.Lock()
@@ -1060,6 +1075,11 @@ func newScenarioRunner(log *scenarioLog) *scenarioRunner {
 	}
 }
 
+func (r *scenarioRunner) ProbeStartup(ctx context.Context) error {
+	r.log.add("startup:runner")
+	return ctx.Err()
+}
+
 func (r *scenarioRunner) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) {
 	return []runner.RepoCandidate{{Name: scenarioRepo, Path: scenarioRepoPath}}, nil
 }
@@ -1183,6 +1203,11 @@ func newScenarioHarness(log *scenarioLog) *scenarioHarness {
 	return &scenarioHarness{log: log, sessions: map[string]harness.Session{}, launches: map[string][]harness.LaunchSpec{}}
 }
 
+func (h *scenarioHarness) ProbeStartup(ctx context.Context) error {
+	h.log.add("startup:harness")
+	return ctx.Err()
+}
+
 func (h *scenarioHarness) ValidateAgent(_ context.Context, _, agent string) error {
 	h.log.add("harness-agent-validated:" + agent)
 	return nil

package/cmd/relay-flow/serve.go

@@ -46,11 +46,12 @@ import (
 // serveRoot is the composition root. It runs the documented startup order
 // and blocks until ctx is canceled, then shuts down in reverse.
 //
-// Order (docs/structs-methods-interfaces.md lines 1081-1097, verbatim):
+// Order (local wiring, machine prerequisites, then durable execution):
 //
 //	flock → load machine config → select task/runner/harness factories →
 //	construct shared runner/harness → load repos + one task.System per repo →
-//	load workflow files with integrity/local checks → bind trusted
+//	check basic machine prerequisites → load workflow files with
+//	integrity/local checks → bind trusted
 //	workflows+matchers to repos → open go-workflows
 //	SQLite engine and start its workers → construct the Run Manager →
 //	start the Repo Poller group → start the Unix-socket server.
@@ -131,6 +132,14 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 		})
 	}
 
+	// Gate all execution, recovery and readiness on machine prerequisites.
+	// This does not run repository/workflow/agent preflight; those checks
+	// remain submission-only. In particular, recovery cannot move aside the
+	// database or touch surviving resources before this phase succeeds.
+	if err := checkStartupPrerequisites(ctx, cfg, rnr, hrn); err != nil {
+		return err
+	}
+
 	// Load workflow files independently. Startup verifies the accepted
 	// integrity hash and performs only cheap local parsing/structure checks;
 	// malformed, legacy, or changed definitions are retained for inspection
@@ -459,6 +468,28 @@ func serveRoot(ctx context.Context, p paths.Paths, recover bool) error {
 	return serveResult
 }
 
+// checkStartupPrerequisites has one aggregate budget independent of workflow
+// and node counts. Each selected adapter owns the narrow probe wire contract;
+// task adapters also own shared-connection deduplication and per-probe limits.
+// These deadlines cover prerequisites, not database opening or engine replay.
+func checkStartupPrerequisites(ctx context.Context, cfg *config.Machine, rnr runner.Runner, hrn harness.Harness) error {
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	if err := task.ProbeStartup(ctx, cfg.TaskPlugin, cfg.TaskConfig, cfg.Repos); err != nil {
+		return fmt.Errorf("startup prerequisite task plugin %q: %w", cfg.TaskPlugin, err)
+	}
+	if err := runner.ProbeStartup(ctx, rnr); err != nil {
+		return fmt.Errorf("startup prerequisite runner plugin %q: %w", cfg.RunnerPlugin, err)
+	}
+	if err := harness.ProbeStartup(ctx, hrn); err != nil {
+		return fmt.Errorf("startup prerequisite harness plugin %q: %w", cfg.HarnessPlugin, err)
+	}
+	if err := ctx.Err(); err != nil {
+		return fmt.Errorf("startup prerequisites: %w", err)
+	}
+	return nil
+}
+
 func recoveryBackupStem(database, stamp string, suffixes []string) (string, error) {
 	for attempt := 0; attempt < 1000; attempt++ {
 		candidateStamp := stamp