waitfor: block until a shell condition holds

--cmd exits 0 (+ optional --matches regex) or --timeout; exit 0/3/1,
last output always printed, --then hook composes with notifyr.
Injectable runner for tests + real-shell integration test.
Spec: doc/tool-parity.md 3.2.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011KikHkfCiC3yELbsMN8fT9

waitfor/wait/wait.go

@@ -0,0 +1,94 @@
+// Package wait blocks until a shell condition holds: run a command
+// every interval until it exits 0 (and, optionally, its output matches
+// a regex) or a timeout expires. One blocking call instead of an
+// agent burning turns on poll loops.
+package wait
+
+import (
+	"fmt"
+	"os/exec"
+	"regexp"
+	"time"
+)
+
+type Options struct {
+	Cmd      string        // shell command to run each attempt (required)
+	Matches  string        // optional regex the output must match
+	Interval time.Duration // between attempts
+	Timeout  time.Duration // total budget
+	Verbose  bool          // progress line per attempt to the log func
+}
+
+type Result struct {
+	Met      bool
+	Attempts int
+	Elapsed  time.Duration
+	LastOut  string
+	LastExit int
+}
+
+// Runner executes a shell command, returning combined output and exit
+// code. Separated out so tests can fake it.
+type Runner func(cmd string) (string, int)
+
+// ShellRunner runs via sh -c with combined stdout+stderr.
+func ShellRunner(cmd string) (string, int) {
+	c := exec.Command("sh", "-c", cmd)
+	out, err := c.CombinedOutput()
+	code := 0
+	if err != nil {
+		code = 1
+		if ee, ok := err.(*exec.ExitError); ok {
+			code = ee.ExitCode()
+		}
+	}
+	return string(out), code
+}
+
+// Wait polls until the condition holds or the timeout expires. The
+// first attempt runs immediately. log receives progress lines when
+// Verbose is set (pass nil otherwise).
+func Wait(opts Options, run Runner, log func(string)) (Result, error) {
+	if opts.Cmd == "" {
+		return Result{}, fmt.Errorf("no command given")
+	}
+	var re *regexp.Regexp
+	if opts.Matches != "" {
+		var err error
+		re, err = regexp.Compile(opts.Matches)
+		if err != nil {
+			return Result{}, fmt.Errorf("bad --matches regex: %v", err)
+		}
+	}
+	if opts.Interval <= 0 {
+		opts.Interval = 10 * time.Second
+	}
+	if opts.Timeout <= 0 {
+		opts.Timeout = 10 * time.Minute
+	}
+	start := time.Now()
+	res := Result{}
+	for {
+		res.Attempts++
+		out, code := run(opts.Cmd)
+		res.LastOut, res.LastExit = out, code
+		met := code == 0 && (re == nil || re.MatchString(out))
+		if opts.Verbose && log != nil {
+			state := "not yet"
+			if met {
+				state = "met"
+			}
+			log(fmt.Sprintf("attempt %d: exit %d, condition %s", res.Attempts, code, state))
+		}
+		if met {
+			res.Met = true
+			res.Elapsed = time.Since(start)
+			return res, nil
+		}
+		if time.Since(start)+opts.Interval > opts.Timeout {
+			res.Elapsed = time.Since(start)
+			return res, nil
+		}
+		time.Sleep(opts.Interval)
+	}
+}

waitfor/wait/wait_test.go

@@ -0,0 +1,92 @@
+package wait
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestMetOnExitZero(t *testing.T) {
+	calls := 0
+	run := func(cmd string) (string, int) {
+		calls++
+		if calls < 3 {
+			return "not ready", 1
+		}
+		return "ready", 0
+	}
+	res, err := Wait(Options{Cmd: "x", Interval: time.Millisecond, Timeout: time.Second}, run, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Met || res.Attempts != 3 || res.LastOut != "ready" {
+		t.Errorf("unexpected result: %+v", res)
+	}
+}
+
+func TestMatchesRequiredOnTopOfExitZero(t *testing.T) {
+	calls := 0
+	run := func(cmd string) (string, int) {
+		calls++
+		if calls == 1 {
+			return "gitea starting", 0 // exit 0 but no match yet
+		}
+		return "gitea healthy", 0
+	}
+	res, err := Wait(Options{Cmd: "x", Matches: "healthy", Interval: time.Millisecond, Timeout: time.Second}, run, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Met || res.Attempts != 2 {
+		t.Errorf("match should gate success: %+v", res)
+	}
+}
+
+func TestTimeoutReportsLastOutput(t *testing.T) {
+	run := func(cmd string) (string, int) { return "still broken", 7 }
+	res, err := Wait(Options{Cmd: "x", Interval: 5 * time.Millisecond, Timeout: 20 * time.Millisecond}, run, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Met {
+		t.Error("should have timed out")
+	}
+	if res.LastOut != "still broken" || res.LastExit != 7 {
+		t.Errorf("last output lost: %+v", res)
+	}
+	if res.Attempts < 1 {
+		t.Error("should have tried at least once")
+	}
+}
+
+func TestBadRegexRejected(t *testing.T) {
+	if _, err := Wait(Options{Cmd: "x", Matches: "("}, nil, nil); err == nil {
+		t.Error("bad regex accepted")
+	}
+}
+
+func TestEmptyCommandRejected(t *testing.T) {
+	if _, err := Wait(Options{}, nil, nil); err == nil {
+		t.Error("empty command accepted")
+	}
+}
+
+// Integration: real shell, waiting for a file to appear (the exact
+// case from the agy live test in doc/tool-parity.md).
+func TestShellRunnerFileAppears(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "flag")
+	go func() {
+		time.Sleep(30 * time.Millisecond)
+		os.WriteFile(path, []byte("x"), 0o644)
+	}()
+	res, err := Wait(Options{
+		Cmd: "test -f " + path, Interval: 10 * time.Millisecond, Timeout: 2 * time.Second,
+	}, ShellRunner, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Met {
+		t.Errorf("file never seen: %+v", res)
+	}
+}