relay-flow 0.3.13-alpha → 0.3.14-alpha

package/internal/harness/startup_test.go

@@ -0,0 +1,85 @@
+package harness_test
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	_ "github.com/rajpopat27/relay-flow/internal/harness/opencode"
+	_ "github.com/rajpopat27/relay-flow/internal/harness/pi"
+)
+
+func TestSelectedHarnessStartupChecksOnlyLocalExecutable(t *testing.T) {
+	for _, name := range []string{"pi", "opencode"} {
+		t.Run(name, func(t *testing.T) {
+			bin := t.TempDir()
+			marker := filepath.Join(t.TempDir(), "invoked")
+			t.Setenv("HARNESS_INVOKED", marker)
+			if err := os.WriteFile(filepath.Join(bin, name), []byte("#!/bin/sh\nprintf '%s' invoked > \"$HARNESS_INVOKED\"\nexit 99\n"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			t.Setenv("PATH", bin)
+			h, err := harness.New(name, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := harness.ProbeStartup(context.Background(), h); err != nil {
+				t.Fatal(err)
+			}
+			if _, err := os.Stat(marker); !os.IsNotExist(err) {
+				t.Fatalf("startup invoked %s instead of resolving it: %v", name, err)
+			}
+			// No fallback to the other installed harness executable.
+			other := "pi"
+			if name == "pi" {
+				other = "opencode"
+			}
+			missing, err := harness.New(other, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := harness.ProbeStartup(context.Background(), missing); err == nil || !strings.Contains(err.Error(), other) {
+				t.Fatalf("missing selected harness = %v", err)
+			}
+			ctx, cancel := context.WithCancel(context.Background())
+			cancel()
+			if err := harness.ProbeStartup(ctx, h); !errors.Is(err, context.Canceled) {
+				t.Fatalf("cancellation = %v", err)
+			}
+		})
+	}
+}
+
+type startupHarness struct {
+	*fakeHarness
+	probe func(context.Context) error
+}
+
+func (h *startupHarness) ProbeStartup(ctx context.Context) error { return h.probe(ctx) }
+
+func TestHarnessStartupDispatchRequiresSupportAndPreservesBudget(t *testing.T) {
+	if err := harness.ProbeStartup(context.Background(), newFakeHarness()); err == nil {
+		t.Fatal("silently skipped selected harness without startup support")
+	}
+	calls := 0
+	failure := errors.New("executable unavailable")
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	deadline, _ := ctx.Deadline()
+	h := &startupHarness{fakeHarness: newFakeHarness(), probe: func(ctx context.Context) error {
+		calls++
+		got, _ := ctx.Deadline()
+		if !got.Equal(deadline) {
+			t.Fatalf("startup extended caller deadline: %v", got)
+		}
+		return failure
+	}}
+	if err := harness.ProbeStartup(ctx, h); !errors.Is(err, failure) || calls != 1 {
+		t.Fatalf("startup = %v, calls=%d", err, calls)
+	}
+}

package/internal/runner/herdr/herdr.go

@@ -76,6 +76,15 @@ func logOutcome(operation, result string, attrs ...any) {
 	slog.Info("herdr outcome", args...)
 }
 
+var _ runner.StartupProber = (*adapter)(nil)
+
+// ProbeStartup checks the selected runtime with one snapshot, not repository
+// discovery (which can issue additional per-workspace Git requests).
+func (a *adapter) ProbeStartup(ctx context.Context) error {
+	_, err := a.cli.Snapshot(ctx)
+	return err
+}
+
 // --- Repos ---
 
 // DiscoverRepos returns the repositories Herdr currently has open, derived

package/internal/runner/herdr/herdrcli/exec.go

@@ -3,11 +3,13 @@ package herdrcli
 import (
 	"bytes"
 	"context"
+	"errors"
 	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"strings"
+	"time"
 )
 
 // execute invokes the installed Herdr executable and keeps its two output
@@ -19,6 +21,8 @@ func (c *CLI) execute(ctx context.Context, args ...string) (stdout, stderr []byt
 	}
 
 	cmd := exec.CommandContext(ctx, "herdr", args...)
+	// Do not let a descendant retaining stdout/stderr defeat cancellation.
+	cmd.WaitDelay = 100 * time.Millisecond
 	cmd.Env = c.environment(os.Environ())
 
 	var out bytes.Buffer
@@ -26,6 +30,16 @@ func (c *CLI) execute(ctx context.Context, args ...string) (stdout, stderr []byt
 	cmd.Stdout = &out
 	cmd.Stderr = &errOut
 	err = cmd.Run()
+	if ctx.Err() != nil {
+		err = fmt.Errorf("herdr executable %q: timeout/cancellation: %w", cmd.Path, ctx.Err())
+	} else if errors.Is(err, exec.ErrNotFound) {
+		err = fmt.Errorf("missing executable %q: %w", cmd.Path, err)
+	} else if err != nil {
+		var exitErr *exec.ExitError
+		if !errors.As(err, &exitErr) {
+			err = fmt.Errorf("herdr executable %q: launch failure: %w", cmd.Path, err)
+		}
+	}
 	return out.Bytes(), errOut.Bytes(), err
 }
 

package/internal/runner/herdr/herdrcli/operations.go

@@ -1,6 +1,9 @@
 package herdrcli
 
-import "context"
+import (
+	"context"
+	"fmt"
+)
 
 type workspaceResponse struct {
 	ID       string             `json:"workspace_id"`
@@ -57,7 +60,7 @@ type foregroundProcessResponse struct {
 
 func (c *CLI) Snapshot(ctx context.Context) (Snapshot, error) {
 	var response struct {
-		Snapshot struct {
+		Snapshot *struct {
 			Workspaces []workspaceResponse `json:"workspaces"`
 			Tabs       []tabResponse       `json:"tabs"`
 			Panes      []paneResponse      `json:"panes"`
@@ -66,6 +69,9 @@ func (c *CLI) Snapshot(ctx context.Context) (Snapshot, error) {
 	if err := c.runJSON(ctx, "api snapshot", &response, "api", "snapshot"); err != nil {
 		return Snapshot{}, err
 	}
+	if response.Snapshot == nil || response.Snapshot.Workspaces == nil || response.Snapshot.Tabs == nil || response.Snapshot.Panes == nil {
+		return Snapshot{}, fmt.Errorf("herdr api snapshot: malformed response: missing snapshot arrays")
+	}
 	return Snapshot{
 		Workspaces: convertWorkspaces(response.Snapshot.Workspaces),
 		Tabs:       convertTabs(response.Snapshot.Tabs),

package/internal/runner/herdr/herdrcli/response.go

@@ -46,6 +46,9 @@ func sentinelFor(code string) error {
 // the operation name and Herdr's own message.
 func (c *CLI) runJSON(ctx context.Context, operation string, dest any, args ...string) error {
 	stdout, stderr, err := c.execute(ctx, args...)
+	if ctx.Err() != nil {
+		return fmt.Errorf("herdr %s: timeout/cancellation: %w", operation, ctx.Err())
+	}
 	if apiErr := decodeError(operation, stderr); apiErr != nil {
 		return apiErr
 	}
@@ -59,6 +62,9 @@ func (c *CLI) runJSON(ctx context.Context, operation string, dest any, args ...s
 // result body or no body at all; only the error envelope matters.
 func (c *CLI) runCommand(ctx context.Context, operation string, args ...string) error {
 	_, stderr, err := c.execute(ctx, args...)
+	if ctx.Err() != nil {
+		return fmt.Errorf("herdr %s: timeout/cancellation: %w", operation, ctx.Err())
+	}
 	if apiErr := decodeError(operation, stderr); apiErr != nil {
 		return apiErr
 	}

package/internal/runner/herdr/herdrcli/startup_test.go

@@ -0,0 +1,101 @@
+package herdrcli
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func installSnapshotLauncher(t *testing.T, script string) {
+	t.Helper()
+	bin := t.TempDir()
+	if err := os.WriteFile(filepath.Join(bin, "herdr"), []byte("#!/bin/sh\n"+script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", bin)
+}
+
+func TestSnapshotAcceptsEmptyRuntimeAndRejectsMalformedResponses(t *testing.T) {
+	for _, tc := range []struct {
+		response string
+		valid    bool
+	}{
+		{`{"result":{"snapshot":{"workspaces":[],"tabs":[],"panes":[]}}}`, true},
+		{`not-json`, false},
+		{`{}`, false},
+		{`{"result":null}`, false},
+		{`{"result":{}}`, false},
+		{`{"result":{"snapshot":null}}`, false},
+		{`{"result":{"snapshot":{}}}`, false},
+		{`{"result":{"snapshot":{"workspaces":null,"tabs":[],"panes":[]}}}`, false},
+	} {
+		t.Run(tc.response, func(t *testing.T) {
+			installSnapshotLauncher(t, "printf '%s' '"+tc.response+"'\n")
+			snapshot, err := New(Options{}).Snapshot(context.Background())
+			if tc.valid {
+				if err != nil || len(snapshot.Workspaces) != 0 || len(snapshot.Tabs) != 0 || len(snapshot.Panes) != 0 {
+					t.Fatalf("empty runtime = %+v, %v", snapshot, err)
+				}
+			} else if err == nil {
+				t.Fatal("accepted malformed snapshot")
+			}
+		})
+	}
+}
+
+func TestSnapshotPassesSelectorsWithExactlyOneRead(t *testing.T) {
+	log := filepath.Join(t.TempDir(), "calls")
+	t.Setenv("SNAPSHOT_CALL_LOG", log)
+	t.Setenv("HERDR_SESSION", "ambient-session")
+	t.Setenv("HERDR_SOCKET_PATH", "/ambient/socket")
+	installSnapshotLauncher(t, `
+[ "$*" = 'api snapshot' ] || exit 2
+[ "$HERDR_SESSION" = 'configured-session' ] || exit 3
+[ "$HERDR_SOCKET_PATH" = '/configured/socket' ] || exit 4
+printf '%s\n' "$*" >> "$SNAPSHOT_CALL_LOG"
+printf '%s' '{"result":{"snapshot":{"workspaces":[],"tabs":[],"panes":[]}}}'
+`)
+	_, err := New(Options{Session: "configured-session", SocketPath: "/configured/socket"}).Snapshot(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	calls, err := os.ReadFile(log)
+	if err != nil || string(calls) != "api snapshot\n" {
+		t.Fatalf("snapshot calls = %q, %v", calls, err)
+	}
+}
+
+func TestSnapshotReportsMissingExecutableAndSocketFailure(t *testing.T) {
+	t.Run("executable", func(t *testing.T) {
+		t.Setenv("PATH", t.TempDir())
+		_, err := New(Options{}).Snapshot(context.Background())
+		if err == nil || !strings.Contains(err.Error(), "missing executable") || !strings.Contains(err.Error(), "herdr") {
+			t.Fatalf("missing executable = %v", err)
+		}
+	})
+	t.Run("socket", func(t *testing.T) {
+		installSnapshotLauncher(t, "printf '%s' '{\"error\":{\"code\":\"connection_refused\",\"message\":\"socket unavailable\"}}' >&2\nexit 1\n")
+		_, err := New(Options{SocketPath: "/configured/socket"}).Snapshot(context.Background())
+		if err == nil || !strings.Contains(err.Error(), "connection_refused") || !strings.Contains(err.Error(), "api snapshot") {
+			t.Fatalf("socket failure = %v", err)
+		}
+	})
+}
+
+func TestSnapshotCancellationBoundsInheritedOutputPipes(t *testing.T) {
+	installSnapshotLauncher(t, "/bin/sleep 2 &\nwait\n")
+	ctx, cancel := context.WithTimeout(context.Background(), 25*time.Millisecond)
+	defer cancel()
+	start := time.Now()
+	_, err := New(Options{}).Snapshot(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)
+	}
+}

package/internal/runner/herdr/startup_test.go

@@ -0,0 +1,58 @@
+package herdr
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/runner/herdr/herdrcli"
+)
+
+type startupClient struct {
+	*fakeClient
+	snapshotCalls int
+	listingCalls  int
+}
+
+func (c *startupClient) Snapshot(ctx context.Context) (herdrcli.Snapshot, error) {
+	c.snapshotCalls++
+	if ctx.Err() != nil {
+		return herdrcli.Snapshot{}, ctx.Err()
+	}
+	return c.snapshot, c.snapshotErr
+}
+
+func (c *startupClient) WorktreeList(context.Context, string) (herdrcli.WorktreeListing, error) {
+	c.listingCalls++
+	return herdrcli.WorktreeListing{}, errors.New("startup must not discover per-workspace repositories")
+}
+
+func TestStartupProbeUsesOnlyOneSnapshot(t *testing.T) {
+	for _, snapshot := range []herdrcli.Snapshot{{}, {
+		Workspaces: []herdrcli.Workspace{{ID: "w1", Label: "app"}},
+		Panes:      []herdrcli.Pane{{ID: "p1", WorkspaceID: "w1", CWD: "/work/app"}},
+	}} {
+		c := &startupClient{fakeClient: &fakeClient{snapshot: snapshot}}
+		if err := runner.ProbeStartup(context.Background(), newAdapter(c)); err != nil {
+			t.Fatal(err)
+		}
+		if c.snapshotCalls != 1 || c.listingCalls != 0 || len(c.workspaceCreateCalls) != 0 || len(c.createCalls) != 0 || len(c.runCalls) != 0 || len(c.closedPanes) != 0 || len(c.closedWorkspaces) != 0 {
+			t.Fatalf("unexpected startup calls: %+v", c)
+		}
+	}
+}
+
+func TestStartupProbePropagatesSnapshotFailureAndCancellation(t *testing.T) {
+	failure := errors.New("herdr socket unavailable")
+	c := &startupClient{fakeClient: &fakeClient{snapshotErr: failure}}
+	a := newAdapter(c)
+	if err := runner.ProbeStartup(context.Background(), a); !errors.Is(err, failure) || c.snapshotCalls != 1 {
+		t.Fatalf("failure = %v, calls=%d", err, c.snapshotCalls)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := runner.ProbeStartup(ctx, a); !errors.Is(err, context.Canceled) || c.snapshotCalls != 2 {
+		t.Fatalf("cancellation = %v, calls=%d", err, c.snapshotCalls)
+	}
+}

package/internal/runner/orca/orca.go

@@ -51,6 +51,15 @@ func New(cli orcacli.Client, raw config.RawValues) (runner.Runner, error) {
 	return &adapter{cli: cli, cfg: cfg}, nil
 }
 
+var _ runner.StartupProber = (*adapter)(nil)
+
+// ProbeStartup checks the Orca runtime without validating any repository or
+// creating worktrees/terminals. An empty repository list is healthy.
+func (a *adapter) ProbeStartup(ctx context.Context) error {
+	_, err := a.cli.ListRepos(ctx)
+	return err
+}
+
 // --- Repos ---
 
 // DiscoverRepos returns Orca-registered repos as registration candidates.

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

@@ -7,9 +7,13 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"os"
 	"os/exec"
+	"path/filepath"
 	"regexp"
+	"runtime"
 	"strings"
+	"time"
 )
 
 var ErrTerminalUnavailable = errors.New("terminal unavailable")
@@ -54,8 +58,12 @@ type Client interface {
 	CloseTerminal(ctx context.Context, handle string) error
 }
 
-// CLI is the production Client backed by the orca binary.
-type CLI struct{}
+// CLI retains the selected launcher and its resolved path for all operations.
+// Construction is local; runtime connectivity is checked by ListRepos.
+type CLI struct {
+	executable string
+	lookupErr  error
+}
 
 // RepoRegistrar is the optional repository-provisioning seam used by the
 // runner adapter. Keeping it separate from Client lets existing read-only
@@ -64,34 +72,63 @@ type RepoRegistrar interface {
 	AddRepo(ctx context.Context, path string) error
 }
 
-func New() *CLI { return &CLI{} }
+func New() *CLI {
+	command := selectCommand(runtime.GOOS, os.Getenv("ORCA_CLI_COMMAND"), os.Getenv("ORCA_DEV_REPO_ROOT"))
+	path, err := exec.LookPath(command)
+	if err == nil {
+		path, err = filepath.Abs(path)
+	}
+	if err != nil {
+		path = command
+	}
+	return &CLI{executable: path, lookupErr: err}
+}
+
+// Orca's explicit session selector takes precedence over the dev launcher.
+// Linux defaults to orca-ide, never the unrelated GNOME screen reader or a
+// legacy alias/shim. Select once; there is no executable fallback.
+func selectCommand(goos, command, devRoot string) string {
+	if command != "" {
+		return command
+	}
+	if devRoot != "" {
+		return "orca-dev"
+	}
+	if goos == "linux" {
+		return "orca-ide"
+	}
+	return "orca"
+}
 
 // AddRepo registers an existing local repository with Orca. Orca derives its
 // display name from the path; relay-flow keeps the user-facing registration
 // name separately.
-func (CLI) AddRepo(ctx context.Context, path string) error {
-	return run(ctx, "repo", "add", "--path", path, "--json")
+func (c CLI) AddRepo(ctx context.Context, path string) error {
+	return c.run(ctx, "repo", "add", "--path", path, "--json")
 }
 
-func (CLI) ListRepos(ctx context.Context) ([]Repo, error) {
+func (c CLI) ListRepos(ctx context.Context) ([]Repo, error) {
 	var res struct {
-		Result struct {
+		Result *struct {
 			Repos []Repo `json:"repos"`
 		} `json:"result"`
 	}
-	if err := runJSON(ctx, &res, "repo", "list", "--json"); err != nil {
+	if err := c.runJSON(ctx, &res, "repo", "list", "--json"); err != nil {
 		return nil, fmt.Errorf("orca repo list: %w", err)
 	}
+	if res.Result == nil || res.Result.Repos == nil {
+		return nil, fmt.Errorf("orca repo list (%s): malformed response: missing result.repos array", c.executable)
+	}
 	return res.Result.Repos, nil
 }
 
-func (CLI) ListWorktrees(ctx context.Context) ([]Worktree, error) {
+func (c CLI) ListWorktrees(ctx context.Context) ([]Worktree, error) {
 	var res struct {
 		Result struct {
 			Worktrees []Worktree `json:"worktrees"`
 		} `json:"result"`
 	}
-	if err := runJSON(ctx, &res, "worktree", "list", "--json"); err != nil {
+	if err := c.runJSON(ctx, &res, "worktree", "list", "--json"); err != nil {
 		return nil, fmt.Errorf("orca worktree list: %w", err)
 	}
 	return res.Result.Worktrees, nil
@@ -100,13 +137,13 @@ func (CLI) ListWorktrees(ctx context.Context) ([]Worktree, error) {
 // CreateWorktree always sets --parent-worktree and --base-branch explicitly
 // (never Orca's inferred defaults) so every ticket worktree has a
 // deliberate, known ancestry.
-func (CLI) CreateWorktree(ctx context.Context, ticketKey, repoID, parentWorktreeID, baseBranch string) error {
-	return run(ctx, "worktree", "create", "--name", ticketKey, "--repo", "id:"+repoID,
+func (c CLI) CreateWorktree(ctx context.Context, ticketKey, repoID, parentWorktreeID, baseBranch string) error {
+	return c.run(ctx, "worktree", "create", "--name", ticketKey, "--repo", "id:"+repoID,
 		"--parent-worktree", "worktree:"+parentWorktreeID, "--base-branch", baseBranch, "--json")
 }
 
-func (CLI) SetWorktreeStatus(ctx context.Context, worktreeID, status string) error {
-	return run(ctx, "worktree", "set", "--worktree", "id:"+worktreeID, "--workspace-status", status, "--json")
+func (c CLI) SetWorktreeStatus(ctx context.Context, worktreeID, status string) error {
+	return c.run(ctx, "worktree", "set", "--worktree", "id:"+worktreeID, "--workspace-status", status, "--json")
 }
 
 // FindExistingBranch returns the first local or remote-tracking branch whose
@@ -127,11 +164,11 @@ func FindExistingBranch(repoPath, ticketKey string) (string, bool, error) {
 	return "", false, nil
 }
 
-func (CLI) DeleteWorktree(ctx context.Context, worktreeID string) error {
-	return run(ctx, "worktree", "rm", "--worktree", "id:"+worktreeID, "--json")
+func (c CLI) DeleteWorktree(ctx context.Context, worktreeID string) error {
+	return c.run(ctx, "worktree", "rm", "--worktree", "id:"+worktreeID, "--json")
 }
 
-func (CLI) ShowTerminal(ctx context.Context, handle string) (Terminal, error) {
+func (c CLI) ShowTerminal(ctx context.Context, handle string) (Terminal, error) {
 	var res struct {
 		Result struct {
 			Terminal struct {
@@ -142,7 +179,7 @@ func (CLI) ShowTerminal(ctx context.Context, handle string) (Terminal, error) {
 			} `json:"terminal"`
 		} `json:"result"`
 	}
-	if err := runJSON(ctx, &res, "terminal", "show", "--terminal", handle, "--json"); err != nil {
+	if err := c.runJSON(ctx, &res, "terminal", "show", "--terminal", handle, "--json"); err != nil {
 		if strings.Contains(err.Error(), "terminal_handle_stale") {
 			return Terminal{}, ErrTerminalUnavailable
 		}
@@ -152,14 +189,14 @@ func (CLI) ShowTerminal(ctx context.Context, handle string) (Terminal, error) {
 	return Terminal{Handle: t.Handle, Title: t.Title, Connected: t.Connected && t.Writable}, nil
 }
 
-func (CLI) SendTerminal(ctx context.Context, handle, text string) error {
-	return run(ctx, "terminal", "send", "--terminal", handle, "--text", text, "--enter", "--json")
+func (c CLI) SendTerminal(ctx context.Context, handle, text string) error {
+	return c.run(ctx, "terminal", "send", "--terminal", handle, "--text", text, "--enter", "--json")
 }
 
 // ListTerminals returns tabs (with their persistent tab-level title) for a
 // worktree, e.g. "name:PAY-101". --include-visual-layouts is mandatory:
 // orca omits visualLayouts from JSON without it.
-func (CLI) ListTerminals(ctx context.Context, worktree string) ([]Terminal, error) {
+func (c CLI) ListTerminals(ctx context.Context, worktree string) ([]Terminal, error) {
 	var res struct {
 		Result struct {
 			VisualLayouts []struct {
@@ -175,7 +212,7 @@ func (CLI) ListTerminals(ctx context.Context, worktree string) ([]Terminal, erro
 			} `json:"visualLayouts"`
 		} `json:"result"`
 	}
-	if err := runJSON(ctx, &res, "terminal", "list", "--worktree", worktree, "--include-visual-layouts", "--json"); err != nil {
+	if err := c.runJSON(ctx, &res, "terminal", "list", "--worktree", worktree, "--include-visual-layouts", "--json"); err != nil {
 		return nil, fmt.Errorf("orca terminal list: %w", err)
 	}
 	var terms []Terminal
@@ -189,7 +226,7 @@ func (CLI) ListTerminals(ctx context.Context, worktree string) ([]Terminal, erro
 
 // CreateTerminal launches the given shell command in a fresh terminal on
 // the ticket's worktree.
-func (CLI) CreateTerminal(ctx context.Context, ticketKey, title, command string) (string, error) {
+func (c CLI) CreateTerminal(ctx context.Context, ticketKey, title, command string) (string, error) {
 	var res struct {
 		Result struct {
 			Terminal struct {
@@ -197,7 +234,7 @@ func (CLI) CreateTerminal(ctx context.Context, ticketKey, title, command string)
 			} `json:"terminal"`
 		} `json:"result"`
 	}
-	if err := runJSON(ctx, &res, "terminal", "create",
+	if err := c.runJSON(ctx, &res, "terminal", "create",
 		"--worktree", "name:"+ticketKey,
 		"--title", title,
 		"--command", command,
@@ -207,8 +244,8 @@ func (CLI) CreateTerminal(ctx context.Context, ticketKey, title, command string)
 	return res.Result.Terminal.Handle, nil
 }
 
-func (CLI) CloseTerminal(ctx context.Context, handle string) error {
-	if err := run(ctx, "terminal", "close", "--terminal", handle, "--json"); err != nil {
+func (c CLI) CloseTerminal(ctx context.Context, handle string) error {
+	if err := c.run(ctx, "terminal", "close", "--terminal", handle, "--json"); err != nil {
 		if strings.Contains(err.Error(), "terminal_handle_stale") {
 			return ErrTerminalUnavailable
 		}
@@ -217,24 +254,52 @@ func (CLI) CloseTerminal(ctx context.Context, handle string) error {
 	return nil
 }
 
-func run(ctx context.Context, args ...string) error {
-	cmd := exec.CommandContext(ctx, "orca", args...)
+func (c CLI) run(ctx context.Context, args ...string) error {
+	if c.lookupErr != nil {
+		return c.commandError(ctx, args, nil, c.lookupErr)
+	}
+	cmd := exec.CommandContext(ctx, c.executable, args...)
+	cmd.WaitDelay = 100 * time.Millisecond
 	out, err := cmd.CombinedOutput()
 	if err != nil {
-		return fmt.Errorf("orca %v: %w: %s", args, err, strings.TrimSpace(string(out)))
+		return c.commandError(ctx, args, out, err)
 	}
 	return nil
 }
 
-func runJSON(ctx context.Context, dest any, args ...string) error {
-	cmd := exec.CommandContext(ctx, "orca", args...)
+func (c CLI) runJSON(ctx context.Context, dest any, args ...string) error {
+	if c.lookupErr != nil {
+		return c.commandError(ctx, args, nil, c.lookupErr)
+	}
+	cmd := exec.CommandContext(ctx, c.executable, args...)
+	cmd.WaitDelay = 100 * time.Millisecond
 	out, err := cmd.Output()
 	if err != nil {
-		// orca prints its JSON error envelope to stdout even on failure.
-		return fmt.Errorf("orca %v: %w: %s", args, err, strings.TrimSpace(string(out)))
+		// Orca prints JSON errors to stdout; launcher failures may use stderr.
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			out = append(out, exitErr.Stderr...)
+		}
+		return c.commandError(ctx, args, out, err)
 	}
 	if err := json.Unmarshal(out, dest); err != nil {
-		return fmt.Errorf("orca %v: parse json: %w", args, err)
+		return fmt.Errorf("orca %s (%s): malformed JSON response: %w", strings.Join(args[:2], " "), c.executable, err)
 	}
 	return nil
 }
+
+// Report safe operation identity, not argv containing commands or prompts.
+func (c CLI) commandError(ctx context.Context, args []string, out []byte, err error) error {
+	operation := strings.Join(args[:2], " ")
+	if ctx.Err() != nil {
+		return fmt.Errorf("orca %s (%s): timeout/cancellation: %w", operation, c.executable, ctx.Err())
+	}
+	if c.lookupErr != nil && (errors.Is(err, exec.ErrNotFound) || errors.Is(err, os.ErrNotExist)) {
+		return fmt.Errorf("orca %s: missing executable %q: %w", operation, c.executable, err)
+	}
+	var exitErr *exec.ExitError
+	if !errors.As(err, &exitErr) {
+		return fmt.Errorf("orca %s (%s): launch failure: %w", operation, c.executable, err)
+	}
+	return fmt.Errorf("orca %s (%s): runtime failure: %w: %s", operation, c.executable, err, strings.TrimSpace(string(out)))
+}

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

@@ -6,6 +6,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 )
@@ -161,7 +162,9 @@ func runGit(t *testing.T, repo string, args ...string) {
 func installStrictFakeOrca(t *testing.T) string {
 	t.Helper()
 	binDir := t.TempDir()
-	fake := filepath.Join(binDir, "orca")
+	t.Setenv("ORCA_CLI_COMMAND", "")
+	t.Setenv("ORCA_DEV_REPO_ROOT", "")
+	fake := filepath.Join(binDir, selectCommand(runtime.GOOS, "", ""))
 	script, err := os.ReadFile(filepath.Join("testdata", "strict-orca.sh"))
 	if err != nil {
 		t.Fatal(err)