relay-flow 0.3.12-alpha → 0.3.14-alpha

package/internal/runner/orca/orcacli/startup_test.go

@@ -0,0 +1,158 @@
+package orcacli
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestLauncherSelection(t *testing.T) {
+	for _, tc := range []struct {
+		os, selector, devRoot, want string
+	}{
+		{"linux", "", "", "orca-ide"},
+		{"darwin", "", "", "orca"},
+		{"windows", "", "", "orca"},
+		{"linux", "", "/dev/orca", "orca-dev"},
+		{"darwin", "", "/dev/orca", "orca-dev"},
+		{"linux", "/session/orca.exe", "/dev/orca", "/session/orca.exe"},
+		{"darwin", "session-orca", "", "session-orca"},
+	} {
+		if got := selectCommand(tc.os, tc.selector, tc.devRoot); got != tc.want {
+			t.Errorf("selectCommand(%q, %q, %q) = %q, want %q", tc.os, tc.selector, tc.devRoot, got, tc.want)
+		}
+	}
+}
+
+func installStartupLauncher(t *testing.T, name, script string) string {
+	t.Helper()
+	bin := t.TempDir()
+	path := filepath.Join(bin, name)
+	if err := os.WriteFile(path, []byte("#!/bin/sh\n"+script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", bin)
+	t.Setenv("ORCA_CLI_COMMAND", name)
+	t.Setenv("ORCA_DEV_REPO_ROOT", "")
+	return path
+}
+
+func TestSelectedLauncherIsResolvedOnceForAllCalls(t *testing.T) {
+	fake := installStrictFakeOrca(t)
+	cli := New()
+	if cli.executable != fake {
+		t.Fatalf("resolved launcher = %q, want %q", cli.executable, fake)
+	}
+	// Neither a client-side selector nor PATH change replaces the server's CLI.
+	t.Setenv("ORCA_CLI_COMMAND", "nonexistent-other-orca")
+	t.Setenv("PATH", t.TempDir()+string(os.PathListSeparator)+os.Getenv("PATH"))
+	if _, err := cli.ListRepos(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := cli.ListWorktrees(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if err := cli.SendTerminal(context.Background(), "term-1", "hello"); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestMissingSelectedLauncherNeverFallsBack(t *testing.T) {
+	installStartupLauncher(t, "orca", "printf '%s' '{\"result\":{\"repos\":[]}}'\n")
+	t.Setenv("ORCA_CLI_COMMAND", "missing-session-launcher")
+	_, err := New().ListRepos(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "missing executable") || !strings.Contains(err.Error(), "missing-session-launcher") {
+		t.Fatalf("missing selector = %v", err)
+	}
+	if runtime.GOOS == "linux" {
+		t.Setenv("ORCA_CLI_COMMAND", "")
+		_, err = New().ListRepos(context.Background())
+		if err == nil || !strings.Contains(err.Error(), "orca-ide") {
+			t.Fatalf("Linux must not invoke bare orca: %v", err)
+		}
+	}
+}
+
+func TestRepoListAcceptsEmptyArrayAndRejectsMalformedResponses(t *testing.T) {
+	for _, tc := range []struct {
+		response string
+		valid    bool
+	}{
+		{`{"result":{"repos":[]}}`, true},
+		{`{}`, false},
+		{`null`, false},
+		{`{"result":null}`, false},
+		{`{"result":{}}`, false},
+		{`{"result":{"repos":null}}`, false},
+		{`{"result":{"repos":{}}}`, false},
+		{`not-json`, false},
+	} {
+		t.Run(tc.response, func(t *testing.T) {
+			installStartupLauncher(t, "selected-orca", "printf '%s' '"+tc.response+"'\n")
+			repos, err := New().ListRepos(context.Background())
+			if tc.valid {
+				if err != nil || repos == nil || len(repos) != 0 {
+					t.Fatalf("empty runtime = %v, %v", repos, err)
+				}
+			} else if err == nil || !strings.Contains(err.Error(), "malformed") {
+				t.Fatalf("malformed response = %v", err)
+			}
+		})
+	}
+}
+
+func TestRepoListReportsLaunchAndRuntimeFailures(t *testing.T) {
+	t.Run("launch", func(t *testing.T) {
+		path := installStartupLauncher(t, "broken-orca", "")
+		if err := os.WriteFile(path, []byte("#!/nonexistent/interpreter\n"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		_, err := New().ListRepos(context.Background())
+		// The selected executable exists, but its interpreter cannot launch.
+		if err == nil || !strings.Contains(err.Error(), "launch failure") || !strings.Contains(err.Error(), path) {
+			t.Fatalf("launch error = %v", err)
+		}
+	})
+	t.Run("connection", func(t *testing.T) {
+		installStartupLauncher(t, "selected-orca", "printf '%s' '{\"error\":{\"code\":\"connection_refused\",\"message\":\"runtime unavailable\"}}'\nexit 1\n")
+		_, err := New().ListRepos(context.Background())
+		if err == nil || !strings.Contains(err.Error(), "connection_refused") || !strings.Contains(err.Error(), "repo list") {
+			t.Fatalf("connection error = %v", err)
+		}
+	})
+	t.Run("stderr", func(t *testing.T) {
+		installStartupLauncher(t, "selected-orca", "printf '%s' 'authentication required' >&2\nexit 1\n")
+		_, err := New().ListRepos(context.Background())
+		if err == nil || !strings.Contains(err.Error(), "authentication required") {
+			t.Fatalf("stderr error = %v", err)
+		}
+	})
+}
+
+func TestRepoListCancellationBoundsInheritedOutputPipes(t *testing.T) {
+	// The background descendant retains both pipes after the launcher is killed.
+	installStartupLauncher(t, "selected-orca", "/bin/sleep 2 &\nwait\n")
+	ctx, cancel := context.WithTimeout(context.Background(), 25*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	_, err := New().ListRepos(ctx)
+	if !errors.Is(err, context.DeadlineExceeded) || !strings.Contains(err.Error(), "timeout") {
+		t.Fatalf("timeout = %v", err)
+	}
+	if elapsed := time.Since(start); elapsed > time.Second {
+		t.Fatalf("inherited pipes defeated deadline: %v", elapsed)
+	}
+}
+
+func TestRuntimeFailureDoesNotExposeCommandArguments(t *testing.T) {
+	installStartupLauncher(t, "selected-orca", "exit 1\n")
+	err := New().SendTerminal(context.Background(), "term-1", "SECRET PROMPT")
+	if err == nil || strings.Contains(err.Error(), "SECRET PROMPT") || !strings.Contains(err.Error(), "terminal send") {
+		t.Fatalf("unsafe operation error = %v", err)
+	}
+}

package/internal/runner/orca/startup_test.go

@@ -0,0 +1,57 @@
+package orca
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/runner/orca/orcacli"
+)
+
+type startupCLI struct {
+	*fakeCLI
+	calls int
+	err   error
+}
+
+func (c *startupCLI) ListRepos(ctx context.Context) ([]orcacli.Repo, error) {
+	c.calls++
+	if ctx.Err() != nil {
+		return nil, ctx.Err()
+	}
+	return c.repos, c.err
+}
+
+func TestStartupProbeReadsRepoListOnceWithoutWrites(t *testing.T) {
+	for _, repos := range [][]orcacli.Repo{nil, {{ID: "r1", Path: "/work/app", DisplayName: "app"}}} {
+		c := &startupCLI{fakeCLI: &fakeCLI{repos: repos}}
+		a, err := New(c, nil)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if err := runner.ProbeStartup(context.Background(), a); err != nil {
+			t.Fatal(err)
+		}
+		if c.calls != 1 || c.createN != 0 || len(c.closedHandles) != 0 || len(c.deletedWorktrees) != 0 || len(c.worktrees) != 0 || c.status != "" {
+			t.Fatalf("unexpected startup effects: %+v", c)
+		}
+	}
+}
+
+func TestStartupProbePropagatesFailureAndCancellation(t *testing.T) {
+	failure := errors.New("orca connection unavailable")
+	c := &startupCLI{fakeCLI: &fakeCLI{}, err: failure}
+	a, err := New(c, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := runner.ProbeStartup(context.Background(), a); !errors.Is(err, failure) || c.calls != 1 {
+		t.Fatalf("failure = %v, calls=%d", err, c.calls)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := runner.ProbeStartup(ctx, a); !errors.Is(err, context.Canceled) || c.calls != 2 {
+		t.Fatalf("cancellation = %v, calls=%d", err, c.calls)
+	}
+}

package/internal/runner/startup.go

@@ -0,0 +1,27 @@
+package runner
+
+import (
+	"context"
+	"fmt"
+	"time"
+)
+
+// StartupProber is the machine-level readiness boundary. Selected runners
+// must implement it; repo validation and discovery remain separate operations.
+// A probe performs one read-only runtime request, with no retries or writes.
+type StartupProber interface {
+	ProbeStartup(context.Context) error
+}
+
+// ProbeStartup checks the selected runner once, within the caller's aggregate
+// startup budget and a five-second per-probe ceiling. Missing probe support is
+// an error, never permission to skip a selected dependency.
+func ProbeStartup(ctx context.Context, selected Runner) error {
+	probe, ok := selected.(StartupProber)
+	if !ok {
+		return fmt.Errorf("selected runner does not implement startup probing")
+	}
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	return probe.ProbeStartup(ctx)
+}

package/internal/runner/startup_test.go

@@ -0,0 +1,59 @@
+package runner_test
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/runner"
+)
+
+type startupRunner struct {
+	*fakeRunner
+	calls int
+	probe func(context.Context) error
+}
+
+func (r *startupRunner) ProbeStartup(ctx context.Context) error {
+	r.calls++
+	return r.probe(ctx)
+}
+
+func TestStartupProbeRequiresSelectedRunnerSupport(t *testing.T) {
+	if err := runner.ProbeStartup(context.Background(), newFakeRunner()); err == nil || !strings.Contains(err.Error(), "startup probing") {
+		t.Fatalf("unsupported selected runner = %v", err)
+	}
+}
+
+func TestStartupProbeIsSingleAttemptWithBoundedDeadline(t *testing.T) {
+	failure := errors.New("runtime unavailable")
+	r := &startupRunner{fakeRunner: newFakeRunner(), probe: func(ctx context.Context) error {
+		deadline, ok := ctx.Deadline()
+		if !ok || time.Until(deadline) > 5*time.Second {
+			t.Fatalf("probe deadline = %v, %v", deadline, ok)
+		}
+		return failure
+	}}
+	if err := runner.ProbeStartup(context.Background(), r); !errors.Is(err, failure) || r.calls != 1 {
+		t.Fatalf("ProbeStartup = %v, calls=%d", err, r.calls)
+	}
+}
+
+func TestStartupProbeHonorsEarlierAggregateDeadline(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 25*time.Millisecond)
+	defer cancel()
+	deadline, _ := ctx.Deadline()
+	r := &startupRunner{fakeRunner: newFakeRunner(), probe: func(probeCtx context.Context) error {
+		got, _ := probeCtx.Deadline()
+		if !got.Equal(deadline) {
+			t.Fatalf("probe extended aggregate deadline: %v > %v", got, deadline)
+		}
+		<-probeCtx.Done()
+		return probeCtx.Err()
+	}}
+	if err := runner.ProbeStartup(ctx, r); !errors.Is(err, context.DeadlineExceeded) || r.calls != 1 {
+		t.Fatalf("ProbeStartup = %v, calls=%d", err, r.calls)
+	}
+}

package/internal/task/beads/bdcli/bdcli.go

@@ -16,6 +16,7 @@ import (
 	"os/exec"
 	"strings"
 	"sync"
+	"time"
 )
 
 // CLI executes bd in one repository and one configured Beads workspace.
@@ -104,6 +105,12 @@ func (e *CommandError) Error() string {
 		return "bd command failed"
 	}
 	message := fmt.Sprintf("bd %v: exit status %d", e.Args, e.ExitCode)
+	if errors.Is(e.cause, context.DeadlineExceeded) || errors.Is(e.cause, context.Canceled) {
+		return fmt.Sprintf("bd %v: timeout/cancellation: %v", e.Args, e.cause)
+	}
+	if e.ExitCode == -1 && e.cause != nil {
+		message += ": launch failure: " + e.cause.Error()
+	}
 	if stderr := strings.TrimSpace(e.Stderr); stderr != "" {
 		message += ": " + stderr
 	}
@@ -241,6 +248,8 @@ func (c *CLI) run(ctx context.Context, args []string, stdin io.Reader) ([]byte,
 	defer c.mu.Unlock()
 
 	cmd := exec.CommandContext(ctx, "bd", args...)
+	// A launcher descendant retaining output pipes must not defeat deadlines.
+	cmd.WaitDelay = 100 * time.Millisecond
 	cmd.Dir = c.repoPath
 	cmd.Env = commandEnvironment(c.repoPath, c.beadsDir)
 	cmd.Stdin = stdin
@@ -249,6 +258,9 @@ func (c *CLI) run(ctx context.Context, args []string, stdin io.Reader) ([]byte,
 	cmd.Stdout = &stdout
 	cmd.Stderr = &stderr
 	if err := cmd.Run(); err != nil {
+		if ctx.Err() != nil {
+			err = ctx.Err()
+		}
 		exitCode := -1
 		var exitErr *exec.ExitError
 		if errors.As(err, &exitErr) && exitErr.ProcessState != nil {

package/internal/task/beads/bdcli/startup.go

@@ -0,0 +1,20 @@
+package bdcli
+
+import (
+	"errors"
+	"fmt"
+	"os/exec"
+)
+
+// CheckExecutable is a local prerequisite check, valid without a configured
+// workspace. It never invokes bd or lets an ambient workspace act as a probe.
+func CheckExecutable() error {
+	_, err := exec.LookPath("bd")
+	if errors.Is(err, exec.ErrNotFound) {
+		return fmt.Errorf("bd startup: missing executable \"bd\": %w", err)
+	}
+	if err != nil {
+		return fmt.Errorf("bd startup: resolve executable \"bd\": %w", err)
+	}
+	return nil
+}

package/internal/task/beads/bdcli/startup_test.go

@@ -0,0 +1,27 @@
+package bdcli
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestProbeDistinguishesSelectedBDLaunchFailure(t *testing.T) {
+	bin := t.TempDir()
+	path := filepath.Join(bin, "bd")
+	if err := os.WriteFile(path, []byte("#!/nonexistent/interpreter\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", bin)
+	if err := CheckExecutable(); err != nil {
+		t.Fatalf("executable resolution unexpectedly launched bd: %v", err)
+	}
+	err := New(t.TempDir(), t.TempDir()).Probe(context.Background())
+	var commandErr *CommandError
+	if !errors.As(err, &commandErr) || !strings.Contains(err.Error(), "launch failure") || !strings.Contains(err.Error(), path) {
+		t.Fatalf("launch failure = %v", err)
+	}
+}

package/internal/task/beads/beads.go

@@ -108,6 +108,7 @@ func init() {
 		ValidateTextConfig: validateTextConfig,
 		New:                newSystem,
 		NewLocal:           newSystemLocal,
+		ProbeStartup:       probeStartup,
 	})
 }
 

package/internal/task/beads/startup.go

@@ -0,0 +1,75 @@
+package beads
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/task/beads/bdcli"
+)
+
+// probeStartup checks only explicitly configured connections, not repository
+// ownership, filters, tickets or history. A shared workspace is probed once.
+func probeStartup(ctx context.Context, root config.RawValues, repos map[string]config.Repo) error {
+	if err := bdcli.CheckExecutable(); err != nil {
+		return err
+	}
+	rootCfg, err := decodeConfig(root)
+	if err != nil {
+		return fmt.Errorf("beads startup root config: %w", err)
+	}
+	workspaces := map[string]string{} // canonical workspace -> code cwd
+	names := make([]string, 0, len(repos))
+	for name := range repos {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		registered := repos[name]
+		dir, err := configuredBeadsDir(root, registered.TaskConfig)
+		if err != nil {
+			return fmt.Errorf("beads startup repo %q: %w", name, err)
+		}
+		dir, err = canonicalBeadsDir(dir)
+		if err != nil {
+			return fmt.Errorf("beads startup repo %q workspace: %w", name, err)
+		}
+		if _, exists := workspaces[dir]; !exists {
+			workspaces[dir] = registered.Path
+		}
+	}
+	// A root connection, when explicitly supplied, must not be silently skipped
+	// even without repos. Prefer an existing code cwd for a shared connection;
+	// otherwise use the explicitly configured workspace, never an ambient cwd.
+	if strings.TrimSpace(rootCfg.BeadsDir) != "" {
+		dir, err := canonicalBeadsDir(rootCfg.BeadsDir)
+		if err != nil {
+			return fmt.Errorf("beads startup root workspace: %w", err)
+		}
+		if _, exists := workspaces[dir]; !exists {
+			workspaces[dir] = dir
+		}
+	}
+	if len(workspaces) == 0 {
+		slog.Info("beads startup connection verification deferred to registration", "reason", "no configured workspace")
+		return nil
+	}
+	dirs := make([]string, 0, len(workspaces))
+	for dir := range workspaces {
+		dirs = append(dirs, dir)
+	}
+	sort.Strings(dirs)
+	for _, dir := range dirs {
+		probeCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
+		err := bdcli.New(workspaces[dir], dir).Probe(probeCtx)
+		cancel()
+		if err != nil {
+			return fmt.Errorf("beads startup workspace probe: %w", err)
+		}
+	}
+	return nil
+}

package/internal/task/beads/startup_test.go

@@ -0,0 +1,155 @@
+package beads
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+func installStartupBD(t *testing.T, script string) string {
+	t.Helper()
+	bin := t.TempDir()
+	log := filepath.Join(t.TempDir(), "calls")
+	t.Setenv("BD_STARTUP_LOG", log)
+	t.Setenv("PATH", bin)
+	t.Setenv("BEADS_DIR", "/ambient/workspace")
+	t.Setenv("BEADS_DB", "/ambient/database")
+	t.Setenv("BD_DB", "/ambient/legacy")
+	if err := os.WriteFile(filepath.Join(bin, "bd"), []byte("#!/bin/sh\n"+script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return log
+}
+
+const startupReadScript = `
+[ "$*" = 'list --ready --limit 1 --no-parent --json' ] || exit 2
+[ -z "${BEADS_DB+x}" ] || exit 3
+[ -z "${BD_DB+x}" ] || exit 4
+printf '%s|%s|%s\n' "$PWD" "$BEADS_DIR" "$*" >> "$BD_STARTUP_LOG"
+printf '%s' '[]'
+`
+
+func TestBeadsStartupWithoutWorkspaceChecksOnlyExecutableAndReportsDeferred(t *testing.T) {
+	log := installStartupBD(t, "printf invoked >> \"$BD_STARTUP_LOG\"\nexit 99\n")
+	var output bytes.Buffer
+	original := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&output, nil)))
+	t.Cleanup(func() { slog.SetDefault(original) })
+	if err := task.ProbeStartup(context.Background(), "beads", nil, nil); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(log); !os.IsNotExist(err) {
+		t.Fatalf("startup probed ambient workspace: %v", err)
+	}
+	if !strings.Contains(output.String(), "deferred to registration") {
+		t.Fatalf("deferred verification not reported: %s", output.String())
+	}
+	t.Setenv("PATH", t.TempDir())
+	if err := task.ProbeStartup(context.Background(), "beads", nil, nil); err == nil || !strings.Contains(err.Error(), "missing executable") {
+		t.Fatalf("missing bd was silently skipped: %v", err)
+	}
+}
+
+func TestBeadsStartupDeduplicatesExplicitWorkspaceAliasesAndPreservesCWD(t *testing.T) {
+	log := installStartupBD(t, startupReadScript)
+	shared, other := t.TempDir(), t.TempDir()
+	alias := filepath.Join(t.TempDir(), "workspace-alias")
+	if err := os.Symlink(shared, alias); err != nil {
+		t.Fatal(err)
+	}
+	codeOne, codeTwo, codeThree := t.TempDir(), t.TempDir(), t.TempDir()
+	repos := map[string]config.Repo{
+		"one":   {Path: codeOne, TaskConfig: config.RawValues{"beadsDir": shared}},
+		"two":   {Path: codeTwo, TaskConfig: config.RawValues{"beadsDir": alias}},
+		"three": {Path: codeThree, TaskConfig: config.RawValues{"beadsDir": other}},
+	}
+	if err := task.ProbeStartup(context.Background(), "beads", config.RawValues{"beadsDir": shared}, repos); err != nil {
+		t.Fatal(err)
+	}
+	calls, err := os.ReadFile(log)
+	if err != nil {
+		t.Fatal(err)
+	}
+	lines := strings.Split(strings.TrimSpace(string(calls)), "\n")
+	if len(lines) != 2 || !strings.Contains(string(calls), codeOne+"|"+shared+"|") || !strings.Contains(string(calls), codeThree+"|"+other+"|") || strings.Contains(string(calls), codeTwo+"|") {
+		t.Fatalf("unexpected deduplicated probes: %s", calls)
+	}
+}
+
+func TestBeadsStartupDoesNotSkipConfiguredRootWorkspaceWithoutRepos(t *testing.T) {
+	log := installStartupBD(t, startupReadScript)
+	workspace := t.TempDir()
+	if err := task.ProbeStartup(context.Background(), "beads", config.RawValues{"beadsDir": workspace}, nil); err != nil {
+		t.Fatal(err)
+	}
+	calls, err := os.ReadFile(log)
+	if err != nil || !strings.HasPrefix(string(calls), workspace+"|"+workspace+"|") || strings.Count(string(calls), "\n") != 1 {
+		t.Fatalf("configured root connection not probed explicitly: %q, %v", calls, err)
+	}
+}
+
+func TestBeadsStartupRejectsInvalidWorkspaceAndNeverFallsBackToRoot(t *testing.T) {
+	log := installStartupBD(t, startupReadScript)
+	for _, tc := range []struct {
+		name string
+		repo config.RawValues
+	}{
+		{"missing-repo-key", nil},
+		{"missing-directory", config.RawValues{"beadsDir": filepath.Join(t.TempDir(), "missing")}},
+		{"wrong-type", config.RawValues{"beadsDir": 123}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			repos := map[string]config.Repo{"app": {Path: t.TempDir(), TaskConfig: tc.repo}}
+			if err := task.ProbeStartup(context.Background(), "beads", config.RawValues{"beadsDir": t.TempDir()}, repos); err == nil {
+				t.Fatal("invalid configured workspace accepted")
+			}
+		})
+	}
+	if _, err := os.Stat(log); !os.IsNotExist(err) {
+		t.Fatalf("invalid config caused an ambient/root fallback read: %v", err)
+	}
+}
+
+func TestBeadsStartupReportsConnectionAndResponseFailuresWithoutRetry(t *testing.T) {
+	for _, tc := range []struct {
+		name, script, want string
+	}{
+		{"connection", "printf '%s' 'Dolt connection refused' >&2\nexit 1\n", "connection refused"},
+		{"malformed", "printf '%s' 'not-json'\n", "JSON"},
+		{"null", "printf '%s' 'null'\n", "JSON"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			log := installStartupBD(t, "printf '%s\\n' called >> \"$BD_STARTUP_LOG\"\n"+tc.script)
+			repos := map[string]config.Repo{"app": {Path: t.TempDir(), TaskConfig: config.RawValues{"beadsDir": t.TempDir()}}}
+			err := task.ProbeStartup(context.Background(), "beads", nil, repos)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("%s = %v", tc.name, err)
+			}
+			calls, err := os.ReadFile(log)
+			if err != nil || string(calls) != "called\n" {
+				t.Fatalf("workspace probe retried: %q, %v", calls, err)
+			}
+		})
+	}
+}
+
+func TestBeadsStartupHonorsEarlierAggregateDeadline(t *testing.T) {
+	installStartupBD(t, "/bin/sleep 2 &\nwait\n")
+	repos := map[string]config.Repo{"app": {Path: t.TempDir(), TaskConfig: config.RawValues{"beadsDir": t.TempDir()}}}
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	err := task.ProbeStartup(ctx, "beads", nil, repos)
+	if !errors.Is(err, context.DeadlineExceeded) || !strings.Contains(err.Error(), "timeout") || time.Since(start) > time.Second {
+		t.Fatalf("startup exceeded caller budget: %v (%v)", err, time.Since(start))
+	}
+}

package/internal/task/factory.go

@@ -44,12 +44,16 @@ type Factory struct {
 	Auth                 func(context.Context, []string, io.Reader) error
 	DefaultConfig        func() config.RawValues
 	ValidateTextConfig   func(config.RawValues) error
+	// ProbeStartup checks machine credentials/connections without constructing
+	// repo systems or validating workflows. Adapters deduplicate connections
+	// and cap each external probe at five seconds within the caller's budget.
+	ProbeStartup func(context.Context, config.RawValues, map[string]config.Repo) error
 	// New constructs a fully validated repo-bound system. It is used by repo
 	// registration, where connectivity must be confirmed immediately.
 	New func(context.Context, RepoSpec) (System, error)
 	// NewLocal constructs only the local adapter state needed for startup. It
-	// must not probe remote services; submission-time validation owns those
-	// checks. Factories without a local constructor retain the old behavior.
+	// must not probe remote services. ProbeStartup owns basic machine checks;
+	// registration/submission owns full repo-specific validation.
 	NewLocal func(context.Context, RepoSpec) (System, error)
 }
 

package/internal/task/jira/jira.go

@@ -335,9 +335,10 @@ func init() {
 			}
 			return strings.Join([]string{creds.Site, proj, comp}, "/"), nil
 		},
-		Auth:     auth,
-		New:      newSystemFromCredentials,
-		NewLocal: newSystemLocal,
+		ProbeStartup: probeStartup,
+		Auth:         auth,
+		New:          newSystemFromCredentials,
+		NewLocal:     newSystemLocal,
 	})
 }