merge origin/master into llm-recording-and-analysis

both sides independently fixed the same three bugs, so each one had to pick a
winner rather than keep both implementations.

extractor encoding: master's recordableValue in worker.go wins over ours in
marshal.go, since master's is pinned by extractor_encoding_test.go and ours had
no tests. our error semantics stay: encodeExtractorValue still returns an error
instead of nil, so an extractor cannot vanish from the trace silently.

apply errors: only the residual generic branch takes master's unconfirmed copy,
where the device may have committed the action before the call failed. the
finer branches that know nothing was dispatched keep lastAction = nil, and our
actionSkipReason taxonomy stays alongside master's held/skippedVerification.

selector matching: our matchAttr with matchSelectorKind wins over master's
match, since ours also handles idPrefix. matchSelector now calls it, which git
did not flag as a conflict and left calling a function our side had deleted.

the ltl doc comment takes master's correction: an unbounded eventually that
never fires IS violated at run end.

internal/testrun/driver.go

@@ -84,6 +84,17 @@ var newDeviceDriver = func(ctx context.Context, options ioscompanion.DeviceOptio
 	return d, d.Close, nil
 }
 
+// newSimulatorDriver constructs the iOS simulator driver and its cleanup. A
+// seam so routing tests assert the run's options reach ioscompanion.Options
+// without spawning a companion.
+var newSimulatorDriver = func(ctx context.Context, options ioscompanion.Options) (driver.DeviceDriver, func(), error) {
+	d, err := ioscompanion.New(ctx, options)
+	if err != nil {
+		return nil, nil, err
+	}
+	return d, d.Close, nil
+}
+
 // buildDriver creates the appropriate DeviceDriver for the platform and returns
 // a cleanup function. For web, ChromeDriver is used directly. An iOS simulator
 // is driven by the native simulator companion (no JVM). A physical iOS device
@@ -99,16 +110,17 @@ func buildDriver(ctx context.Context, options Options, stdout io.Writer) (driver
 	}
 
 	if options.Platform == "ios" && options.iosIsSimulator {
-		d, err := ioscompanion.New(ctx, ioscompanion.Options{
+		d, cleanup, err := newSimulatorDriver(ctx, ioscompanion.Options{
 			UniqueDeviceIdentifier: options.iosUDID,
 			BundleID:               options.BundleID,
 			AppPath:                options.IosAppPath,
+			ClearState:             options.ClearData,
 			Output:                 stdout,
 		})
 		if err != nil {
 			return nil, nil, fmt.Errorf("ios simulator driver: %w", err)
 		}
-		return d, d.Close, nil
+		return d, cleanup, nil
 	}
 
 	if options.Platform == "ios" {
@@ -117,6 +129,7 @@ func buildDriver(ctx context.Context, options Options, stdout io.Writer) (driver
 			CoreDeviceID: options.iosCoreDeviceID,
 			BundleID:     options.BundleID,
 			AppPath:      options.IosAppPath,
+			ClearState:   options.ClearData,
 			Output:       stdout,
 		})
 		if err != nil {
@@ -148,10 +161,14 @@ func buildDriver(ctx context.Context, options Options, stdout io.Writer) (driver
 	if options.Device != "" {
 		sidecarArgs = append(sidecarArgs, "--serial", options.Device)
 	}
+	adbPath, err := android.AdbBinary()
+	if err != nil {
+		return nil, nil, preflightFailure("android", err)
+	}
 	sidecarCommand := exec.CommandContext(ctx, "java", sidecarArgs...)
 	sidecarCommand.Stdout = stdout
 	sidecarCommand.Stderr = stdout
-	sidecarCommand.Env = android.EnvWithAndroidPlatformTools(os.Environ())
+	sidecarCommand.Env = android.EnvWithAndroidPlatformTools(os.Environ(), adbPath)
 	// SIGTERM lets the sidecar's shutdown hook stop the iOS XCTest runner.
 	// SIGKILL skips the hook and orphans an xcodebuild session that later
 	// restarts its runner and hijacks the simulator mid-run.
@@ -162,11 +179,13 @@ func buildDriver(ctx context.Context, options Options, stdout io.Writer) (driver
 	if err := sidecarCommand.Start(); err != nil {
 		return nil, nil, fmt.Errorf("spawn sidecar: %w", err)
 	}
-	fmt.Fprintf(stdout, "sidecar pid=%d listening on 127.0.0.1:%d\n", sidecarCommand.Process.Pid, sidecarPort)
+	sidecarExited := watchSidecar(sidecarCommand)
+	address := fmt.Sprintf("127.0.0.1:%d", sidecarPort)
+	fmt.Fprintf(stdout, "sidecar pid=%d listening on %s (adb: %s)\n", sidecarCommand.Process.Pid, address, adbPath)
 
-	driverClient, err := driverSidecar.Dial(fmt.Sprintf("127.0.0.1:%d", sidecarPort))
+	driverClient, err := driverSidecar.Dial(address)
 	if err != nil {
-		stopSidecar(sidecarCommand)
+		stopSidecar(sidecarCommand, sidecarExited)
 		return nil, nil, fmt.Errorf("dial sidecar: %w", err)
 	}
 	driverClient.SetPlatform(options.Platform)
@@ -175,22 +194,82 @@ func buildDriver(ctx context.Context, options Options, stdout io.Writer) (driver
 	// (absorbing the XCUITest startup race) runs inside IosDriverBackend.init
 	// in the sidecar - no additional sleep needed here.
 	healthCtx, healthCancel := context.WithTimeout(ctx, sidecarStartupTimeout)
-	if err := driverClient.WaitForHealth(healthCtx, 250e6); err != nil {
-		healthCancel()
-		stopSidecar(sidecarCommand)
-		_ = driverClient.Close()
-		return nil, nil, fmt.Errorf("sidecar health check: %w", err)
-	}
+	healthErr := awaitSidecar(healthCtx, address, sidecarStartupTimeout, func(pollCtx context.Context) error {
+		return driverClient.WaitForHealth(pollCtx, 250e6)
+	}, sidecarExited)
 	healthCancel()
+	if healthErr != nil {
+		stopSidecar(sidecarCommand, sidecarExited)
+		_ = driverClient.Close()
+		return nil, nil, healthErr
+	}
 	fmt.Fprintln(stdout, "sidecar is healthy")
 
 	cleanup := func() {
 		_ = driverClient.Close()
-		stopSidecar(sidecarCommand)
+		stopSidecar(sidecarCommand, sidecarExited)
 	}
 	return driverClient, cleanup, nil
 }
 
+// watchSidecar reaps the sidecar and publishes its exit status. The channel is
+// closed after the send so the shutdown path can still receive once the startup
+// path has taken the status.
+func watchSidecar(sidecarCommand *exec.Cmd) <-chan error {
+	exited := make(chan error, 1)
+	go func() {
+		exited <- sidecarCommand.Wait()
+		close(exited)
+	}()
+	return exited
+}
+
+// awaitSidecar waits for the sidecar to answer a health check, racing that
+// against the process exiting so a sidecar that dies during startup is reported
+// as the exit it was rather than as a deadline half a minute later. Neither
+// failure knows why the sidecar was unhappy, so both name what to look at
+// instead of picking a cause.
+func awaitSidecar(
+	ctx context.Context,
+	address string,
+	timeout time.Duration,
+	health func(context.Context) error,
+	exited <-chan error,
+) error {
+	healthy := make(chan error, 1)
+	go func() { healthy <- health(ctx) }()
+	select {
+	case exitErr := <-exited:
+		return sidecarExitedError(address, exitErr)
+	case err := <-healthy:
+		if err == nil {
+			return nil
+		}
+		select {
+		case exitErr := <-exited:
+			return sidecarExitedError(address, exitErr)
+		default:
+			return fmt.Errorf(
+				"sidecar did not answer a health check on %s within %s and is still running\n%s",
+				address, timeout, sidecarWhatToCheck,
+			)
+		}
+	}
+}
+
+const sidecarWhatToCheck = "check the sidecar output above, then `sanderling doctor --platform=android` (java 17+, adb, Android SDK)"
+
+func sidecarExitedError(address string, exitErr error) error {
+	status := "exit status 0"
+	if exitErr != nil {
+		status = exitErr.Error()
+	}
+	return fmt.Errorf(
+		"sidecar exited before it answered a health check on %s: %s\n%s",
+		address, status, sidecarWhatToCheck,
+	)
+}
+
 // sidecarShutdownGrace bounds how long the sidecar gets to run its shutdown
 // hook (terminate the app, stop the XCTest runner) before being killed.
 const sidecarShutdownGrace = 15 * time.Second
@@ -198,25 +277,20 @@ const sidecarShutdownGrace = 15 * time.Second
 // stopSidecar terminates the sidecar gracefully so its shutdown hook can stop
 // the device-side runner processes, escalating to SIGKILL when it does not
 // exit within the grace window.
-func stopSidecar(sidecarCommand *exec.Cmd) {
+func stopSidecar(sidecarCommand *exec.Cmd, exited <-chan error) {
 	if sidecarCommand.Process == nil {
 		return
 	}
 	if err := sidecarCommand.Process.Signal(syscall.SIGTERM); err != nil {
 		_ = sidecarCommand.Process.Kill()
-		_ = sidecarCommand.Wait()
+		<-exited
 		return
 	}
-	done := make(chan struct{})
-	go func() {
-		_ = sidecarCommand.Wait()
-		close(done)
-	}()
 	select {
-	case <-done:
+	case <-exited:
 	case <-time.After(sidecarShutdownGrace):
 		_ = sidecarCommand.Process.Kill()
-		<-done
+		<-exited
 	}
 }
 

internal/testrun/driver_test.go

@@ -4,7 +4,10 @@ import (
 	"context"
 	"errors"
 	"io"
+	"os/exec"
+	"strings"
 	"testing"
+	"time"
 
 	"github.com/priyanshujain/sanderling/internal/driver"
 	"github.com/priyanshujain/sanderling/internal/driver/ioscompanion"
@@ -27,7 +30,7 @@ func TestBuildDriverRoutesPhysicalIOSToDeviceDriver(t *testing.T) {
 		return stubDeviceDriver{}, func() { closed = true }, nil
 	}
 
-	options := Options{Platform: "ios", BundleID: "app.folio", IosAppPath: "/tmp/iosApp.app"}
+	options := Options{Platform: "ios", BundleID: "app.folio", IosAppPath: "/tmp/iosApp.app", ClearData: true}
 	options.iosIsSimulator = false
 	options.iosUDID = "00008140-HW"
 	options.iosCoreDeviceID = "CORE-1"
@@ -45,12 +48,41 @@ func TestBuildDriverRoutesPhysicalIOSToDeviceDriver(t *testing.T) {
 	if got.BundleID != "app.folio" || got.AppPath != "/tmp/iosApp.app" {
 		t.Fatalf("DeviceOptions = %+v, want bundle and app path threaded through", got)
 	}
+	if !got.ClearState {
+		t.Fatalf("DeviceOptions = %+v, want clear-data threaded through: the driver clears before its session, so a launch cannot", got)
+	}
 	cleanup()
 	if !closed {
 		t.Fatal("cleanup must close the device driver")
 	}
 }
 
+func TestBuildDriverThreadsClearStateToTheSimulatorDriver(t *testing.T) {
+	stubPreflight(t)
+	original := newSimulatorDriver
+	t.Cleanup(func() { newSimulatorDriver = original })
+
+	var got ioscompanion.Options
+	newSimulatorDriver = func(_ context.Context, options ioscompanion.Options) (driver.DeviceDriver, func(), error) {
+		got = options
+		return stubDeviceDriver{}, func() {}, nil
+	}
+
+	options := Options{Platform: "ios", BundleID: "app.folio", IosAppPath: "/tmp/iosApp.app", ClearData: true}
+	options.iosIsSimulator = true
+	options.iosUDID = "SIM-UDID"
+
+	if _, _, err := buildDriver(context.Background(), options, io.Discard); err != nil {
+		t.Fatalf("buildDriver: %v", err)
+	}
+	if got.UniqueDeviceIdentifier != "SIM-UDID" || got.BundleID != "app.folio" || got.AppPath != "/tmp/iosApp.app" {
+		t.Fatalf("Options = %+v, want the resolved target, bundle and app path", got)
+	}
+	if !got.ClearState {
+		t.Fatalf("Options = %+v, want clear-data threaded through: the driver clears before its session, so a launch cannot", got)
+	}
+}
+
 func TestBuildDriverSurfacesDeviceConstructionError(t *testing.T) {
 	stubPreflight(t)
 	original := newDeviceDriver
@@ -65,6 +97,130 @@ func TestBuildDriverSurfacesDeviceConstructionError(t *testing.T) {
 	}
 }
 
+// A sidecar that dies during startup leaves the health poll with nothing to
+// talk to, and reporting that as a deadline sends the reader after a gRPC
+// timeout instead of the exit that already happened.
+func TestAwaitSidecarReportsTheExitItSaw(t *testing.T) {
+	exited := make(chan error, 1)
+	exited <- errors.New("exit status 1")
+	close(exited)
+
+	err := awaitSidecar(
+		context.Background(),
+		"127.0.0.1:54321",
+		30*time.Second,
+		func(ctx context.Context) error { <-ctx.Done(); return ctx.Err() },
+		exited,
+	)
+	if err == nil {
+		t.Fatal("expected an error when the sidecar exits before it is healthy")
+	}
+	for _, want := range []string{
+		"sidecar exited before it answered a health check on 127.0.0.1:54321: exit status 1",
+		"check the sidecar output above",
+		"sanderling doctor --platform=android",
+	} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q missing %q", err, want)
+		}
+	}
+}
+
+func TestAwaitSidecarTimeoutSaysOnlyWhatItObserved(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+
+	err := awaitSidecar(
+		ctx,
+		"127.0.0.1:54321",
+		50*time.Millisecond,
+		func(ctx context.Context) error { <-ctx.Done(); return ctx.Err() },
+		make(chan error, 1),
+	)
+	if err == nil {
+		t.Fatal("expected an error when the sidecar never answers")
+	}
+	for _, want := range []string{
+		"sidecar did not answer a health check on 127.0.0.1:54321 within 50ms and is still running",
+		"check the sidecar output above",
+		"sanderling doctor --platform=android",
+	} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q missing %q", err, want)
+		}
+	}
+	if strings.Contains(err.Error(), "context deadline exceeded") {
+		t.Errorf("error %q must not hand the reader a bare gRPC deadline", err)
+	}
+}
+
+func TestAwaitSidecarHealthyReturnsNil(t *testing.T) {
+	err := awaitSidecar(
+		context.Background(),
+		"127.0.0.1:54321",
+		30*time.Second,
+		func(context.Context) error { return nil },
+		make(chan error, 1),
+	)
+	if err != nil {
+		t.Fatalf("expected a healthy sidecar to pass, got %v", err)
+	}
+}
+
+func TestStopSidecarTerminatesARunningSidecar(t *testing.T) {
+	command := exec.Command("sleep", "60")
+	if err := command.Start(); err != nil {
+		t.Fatalf("start: %v", err)
+	}
+	exited := watchSidecar(command)
+
+	stopped := make(chan struct{})
+	go func() {
+		stopSidecar(command, exited)
+		close(stopped)
+	}()
+	select {
+	case <-stopped:
+	case <-time.After(10 * time.Second):
+		t.Fatal("stopSidecar never returned for a running sidecar")
+	}
+	if got := command.ProcessState.String(); got != "signal: terminated" {
+		t.Errorf("sidecar ended as %q, want the SIGTERM its shutdown hook needs", got)
+	}
+}
+
+// The startup path takes the exit status to report it, so the shutdown path
+// that follows must not sit waiting for a status nobody will send again.
+func TestStopSidecarAfterTheStartupPathTookTheExitStatus(t *testing.T) {
+	command := exec.Command("sh", "-c", "exit 3")
+	if err := command.Start(); err != nil {
+		t.Fatalf("start: %v", err)
+	}
+	exited := watchSidecar(command)
+
+	err := awaitSidecar(
+		context.Background(),
+		"127.0.0.1:54321",
+		30*time.Second,
+		func(ctx context.Context) error { <-ctx.Done(); return ctx.Err() },
+		exited,
+	)
+	if err == nil || !strings.Contains(err.Error(), "exit status 3") {
+		t.Fatalf("expected the sidecar's real exit status, got %v", err)
+	}
+
+	stopped := make(chan struct{})
+	go func() {
+		stopSidecar(command, exited)
+		close(stopped)
+	}()
+	select {
+	case <-stopped:
+	case <-time.After(10 * time.Second):
+		t.Fatal("stopSidecar blocked on an exit status the startup path had already taken")
+	}
+}
+
 // stubPreflight bypasses the host-readiness checks so routing tests exercise
 // driver construction on a Linux CI runner that lacks xcrun/java.
 func stubPreflight(t *testing.T) {

internal/testrun/preflight.go

@@ -4,6 +4,8 @@ import (
 	"context"
 	"fmt"
 	"os/exec"
+
+	"github.com/priyanshujain/sanderling/internal/android"
 )
 
 // Preflight runs platform-specific host checks before sidecar/driver setup.
@@ -18,7 +20,15 @@ func Preflight(ctx context.Context, platform string) error {
 
 type preflightFunc func(name string) error
 
+// preflightCheck resolves adb through the same helper every adb call in a run
+// uses, so a host whose SDK is only reachable through $ANDROID_HOME or a
+// standard install location is not turned away here and then driven fine by
+// the rest of the pipeline.
 func preflightCheck(name string) error {
+	if name == "adb" {
+		_, err := android.AdbBinary()
+		return err
+	}
 	if _, err := exec.LookPath(name); err != nil {
 		return fmt.Errorf("%s not found on PATH: %w", name, err)
 	}

internal/testrun/preflight_test.go

@@ -3,6 +3,8 @@ package testrun
 import (
 	"context"
 	"errors"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 )
@@ -49,6 +51,33 @@ func TestPreflight_AndroidNeedsAdbAndJava(t *testing.T) {
 	}
 }
 
+// Every adb call in an android run resolves through $ANDROID_HOME and the
+// standard SDK locations, so a preflight that only looks at PATH turns away a
+// host the run itself would drive.
+func TestPreflight_AndroidAcceptsAdbUnderAndroidHome(t *testing.T) {
+	sdk := t.TempDir()
+	writeExecutable(t, filepath.Join(sdk, "platform-tools", "adb"))
+	pathDirectory := t.TempDir()
+	writeExecutable(t, filepath.Join(pathDirectory, "java"))
+	t.Setenv("PATH", pathDirectory)
+	t.Setenv("ANDROID_HOME", sdk)
+	t.Setenv("ANDROID_SDK_ROOT", "")
+
+	if err := Preflight(context.Background(), "android"); err != nil {
+		t.Fatalf("Preflight with adb under $ANDROID_HOME: %v", err)
+	}
+}
+
+func writeExecutable(t *testing.T, path string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("mkdir %s: %v", filepath.Dir(path), err)
+	}
+	if err := os.WriteFile(path, nil, 0o755); err != nil {
+		t.Fatalf("write %s: %v", path, err)
+	}
+}
+
 func TestPreflight_iOSNeedsXcrun(t *testing.T) {
 	check := func(name string) error {
 		if name == "xcrun" {

internal/testrun/testrun.go

@@ -247,7 +247,15 @@ func Execute(ctx context.Context, options Options, stdout io.Writer) error {
 // --exit-on-violation a run that found violations is still a successful run
 // (the summary reports them), which is the behaviour every existing caller
 // depends on.
+//
+// A run none of whose steps reached the verifier fails whatever the flags say,
+// because it holds no verdict to report. The threshold is every step and not a
+// fraction of them: a screen that composes now and then costs a healthy android
+// run a step or two, and a check that fired on those would be red on every run.
 func runOutcome(options Options, summary runner.Summary) error {
+	if summary.Steps > 0 && summary.SkippedVerification == summary.Steps {
+		return VacuousRunError{Steps: summary.Steps}
+	}
 	if options.ExitOnViolation && len(summary.Violations) > 0 {
 		return ViolationsError{Count: len(summary.Violations)}
 	}
@@ -283,6 +291,22 @@ func BundleSpec(specPath string, seed int64) (bundler.Result, error) {
 	})
 }
 
+// VacuousRunError reports a run in which no step reached the verifier, so no
+// property ever judged anything. It is not a clean run and it is not a found
+// bug: it is a run that produced no evidence either way, and the absence of
+// violations in it says nothing about the app. It stays untyped to the CLI's
+// violation path on purpose, so it exits 1 as a broken run rather than 2.
+type VacuousRunError struct {
+	Steps int
+}
+
+func (e VacuousRunError) Error() string {
+	return fmt.Sprintf(
+		"%d step(s) ran and none of them reached the verifier: the screen was "+
+			"still moving every time it was read, so no property judged this run",
+		e.Steps)
+}
+
 // bundleInputs holds the pre-driver assembly: alias map, seed, esbuild defines,
 // and the resolved spec-API/goja-runtime paths the bundler consumes.
 type bundleInputs struct {
@@ -372,16 +396,20 @@ func resolveRuntimeSibling(specAPIPath, userSpecPath, filename string) string {
 	return ""
 }
 
-// resolveSpecAPIPath returns the path to pkg/spec/src/index.ts inside
-// a sanderling source checkout, searched upward from the spec file and the cwd.
-// Returns "" when not found, in which case esbuild resolves @sanderling/spec via
-// node_modules the way a downstream user's project would.
+// resolveSpecAPIPath returns the path to the spec API's index.ts: a sanderling
+// source checkout first, searched upward from the spec file and the cwd, then
+// an installed node_modules/@sanderling/spec. Aliasing the installed copy is
+// what keeps the spec and the runtime entry on one module graph; resolving the
+// bare specifier through package.json "exports" would load dist/ alongside the
+// runtime's src/ and give sampler-rng.ts two instances.
 func resolveSpecAPIPath(specPath string) string {
-	var candidates []string
+	var checkout, installed []string
 	if absoluteSpec, err := filepath.Abs(specPath); err == nil {
 		directory := filepath.Dir(absoluteSpec)
 		for {
-			candidates = append(candidates, filepath.Join(directory, "pkg/spec/src/index.ts"))
+			checkout = append(checkout, filepath.Join(directory, "pkg/spec/src/index.ts"))
+			installed = append(installed,
+				filepath.Join(directory, "node_modules/@sanderling/spec/src/index.ts"))
 			parent := filepath.Dir(directory)
 			if parent == directory {
 				break
@@ -390,9 +418,9 @@ func resolveSpecAPIPath(specPath string) string {
 		}
 	}
 	if cwd, err := os.Getwd(); err == nil {
-		candidates = append(candidates, filepath.Join(cwd, "pkg/spec/src/index.ts"))
+		checkout = append(checkout, filepath.Join(cwd, "pkg/spec/src/index.ts"))
 	}
-	for _, candidate := range candidates {
+	for _, candidate := range append(checkout, installed...) {
 		if _, err := os.Stat(candidate); err == nil {
 			return candidate
 		}

internal/testrun/testrun_test.go

@@ -2,7 +2,9 @@ package testrun
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
@@ -287,6 +289,31 @@ func TestRunOutcome_ReportsViolationsOnlyUnderTheFlag(t *testing.T) {
 	}
 }
 
+// A step the verifier skipped was judged by nothing, so a run whose every step
+// was skipped holds no verdict at all: "no violations" there is the absence of
+// an answer rather than a clean one. Reporting it as a successful run is the
+// green and vacuous outcome structuralShape's own design notes call worse than
+// the composition it catches, and the runner's hold is what makes a fully
+// skipped run reachable.
+func TestRunOutcome_ARunThatJudgedNothingIsNotASuccess(t *testing.T) {
+	nothingJudged := runner.Summary{Steps: 6, SkippedVerification: 6}
+	err := runOutcome(Options{}, nothingJudged)
+	var vacuous VacuousRunError
+	if !errors.As(err, &vacuous) {
+		t.Fatalf("a run that judged none of its 6 steps came back %v, want a VacuousRunError", err)
+	}
+	if vacuous.Steps != 6 {
+		t.Errorf("steps: got %d, want 6", vacuous.Steps)
+	}
+
+	// A screen that composes now and then costs a run steps, not its verdict. A
+	// check that fired here would turn every healthy android run red.
+	mostlyJudged := runner.Summary{Steps: 6, SkippedVerification: 5}
+	if err := runOutcome(Options{}, mostlyJudged); err != nil {
+		t.Errorf("a run that judged one of its 6 steps must succeed, got %v", err)
+	}
+}
+
 // wedgedLaunchDriver never returns from Launch, standing in for a driver whose
 // device-side session is stuck.
 type wedgedLaunchDriver struct {
@@ -327,3 +354,153 @@ func TestLaunchAppBoundsWedgedDriver(t *testing.T) {
 		t.Fatal("launchApp never returned: the pre-run launch is unbounded, so a wedged driver hangs the run forever")
 	}
 }
+
+// repoFile walks up from the test's working directory and returns the absolute
+// path of rel inside the sanderling checkout.
+func repoFile(t *testing.T, rel string) string {
+	t.Helper()
+	directory, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for {
+		candidate := filepath.Join(directory, rel)
+		if _, err := os.Stat(candidate); err == nil {
+			return candidate
+		}
+		parent := filepath.Dir(directory)
+		if parent == directory {
+			t.Fatalf("%s not found above the test directory", rel)
+		}
+		directory = parent
+	}
+}
+
+// publishedFiles returns the "files" entries of pkg/spec/package.json, the
+// exact set npm ships in the @sanderling/spec tarball.
+func publishedFiles(t *testing.T) []string {
+	t.Helper()
+	raw, err := os.ReadFile(repoFile(t, "pkg/spec/package.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var manifest struct {
+		Files []string `json:"files"`
+	}
+	if err := json.Unmarshal(raw, &manifest); err != nil {
+		t.Fatal(err)
+	}
+	return manifest.Files
+}
+
+// installPublishedPackage reproduces what `npm install @sanderling/spec`
+// unpacks into node_modules: only the paths package.json publishes.
+func installPublishedPackage(t *testing.T, dest string) {
+	t.Helper()
+	specDir := filepath.Dir(repoFile(t, "pkg/spec/package.json"))
+	for _, entry := range publishedFiles(t) {
+		source := filepath.Join(specDir, entry)
+		if _, err := os.Stat(source); err != nil {
+			continue
+		}
+		copyTree(t, source, filepath.Join(dest, entry))
+	}
+}
+
+func copyTree(t *testing.T, source, dest string) {
+	t.Helper()
+	err := filepath.WalkDir(source, func(path string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		relative, err := filepath.Rel(source, path)
+		if err != nil {
+			return err
+		}
+		target := filepath.Join(dest, relative)
+		if entry.IsDir() {
+			return os.MkdirAll(target, 0o755)
+		}
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+			return err
+		}
+		return os.WriteFile(target, data, 0o644)
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+// TestResolveRuntimeSibling_PublishedPackageShipsTheRuntimes pins npm's "files"
+// list against the resolver that consumes it. The tarball shipped dist/ alone
+// while the node_modules fallback looks for src/goja-runtime.ts, so every
+// `npm install @sanderling/spec` user hit "goja-runtime.ts not found".
+func TestResolveRuntimeSibling_PublishedPackageShipsTheRuntimes(t *testing.T) {
+	root := t.TempDir()
+	installPublishedPackage(t, filepath.Join(root, "node_modules", "@sanderling", "spec"))
+	specPath := filepath.Join(root, "spec.ts")
+	if err := os.WriteFile(specPath, []byte(""), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	for _, filename := range []string{"goja-runtime.ts", "web-runtime.ts"} {
+		if resolveRuntimeSibling("", specPath, filename) == "" {
+			t.Errorf("%s unreachable from a published install; package.json publishes %v",
+				filename, publishedFiles(t))
+		}
+	}
+}
+
+// TestPrepareBundleInputs_InstalledPackageSharesOneModuleGraph pins the
+// downstream case: with no sanderling checkout above the spec, the aliases and
+// the runtime entry must name the SAME installed copy. An unset alias let
+// esbuild resolve @sanderling/spec to dist/ while the runtime came from src/,
+// which loads sampler-rng.ts twice; from(), strings(), integers() and emails()
+// then read an rng the picker never set and collapse to a fixed default.
+func TestPrepareBundleInputs_InstalledPackageSharesOneModuleGraph(t *testing.T) {
+	root := t.TempDir()
+	installed := filepath.Join(root, "node_modules", "@sanderling", "spec")
+	installPublishedPackage(t, installed)
+	specPath := filepath.Join(root, "sanderling", "spec.ts")
+	if err := os.MkdirAll(filepath.Dir(specPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(specPath, []byte(""), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(cwd) })
+	if err := os.Chdir(root); err != nil {
+		t.Fatal(err)
+	}
+
+	prep, err := prepareBundleInputs(Options{Spec: specPath})
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := filepath.Join(installed, "src")
+	want := map[string]string{
+		"@sanderling/spec":                     filepath.Join(source, "index.ts"),
+		"@sanderling/spec/defaults":            filepath.Join(source, "defaults/index.ts"),
+		"@sanderling/spec/defaults/properties": filepath.Join(source, "defaults/properties.ts"),
+	}
+	for key, wantValue := range want {
+		if prep.aliases[key] != wantValue {
+			t.Errorf("alias %q = %q, want %q", key, prep.aliases[key], wantValue)
+		}
+	}
+	if got := prep.gojaRuntimePath; got != filepath.Join(source, "goja-runtime.ts") {
+		t.Errorf("gojaRuntimePath = %q, want it beside the aliased index.ts", got)
+	}
+	if got := resolveWebRuntimePath(prep.specAPIPath, specPath); got != filepath.Join(source, "web-runtime.ts") {
+		t.Errorf("webRuntimePath = %q, want it beside the aliased index.ts", got)
+	}
+}