relay-flow 0.2.3-alpha → 0.2.4-alpha

package/internal/harness/pi/config_test.go

@@ -0,0 +1,46 @@
+package pi
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/harness"
+)
+
+func TestPiHarnessConfigUsesDocumentedDefaults(t *testing.T) {
+	defaults, err := harness.Defaults("pi")
+	if err != nil {
+		t.Fatalf("harness.Defaults(pi): %v", err)
+	}
+	if defaults["initial"] != defaultInitialPrompt {
+		t.Fatalf("initial default = %#v, want %#v", defaults["initial"], defaultInitialPrompt)
+	}
+	if defaults["feedback"] != defaultFeedbackPrompt {
+		t.Fatalf("feedback default = %#v, want %#v", defaults["feedback"], defaultFeedbackPrompt)
+	}
+	if _, ok := defaults["hitl"]; ok {
+		t.Fatalf("Pi defaults unexpectedly contain a HITL prompt: %#v", defaults["hitl"])
+	}
+}
+
+func TestPiHarnessConfigRejectsNonTemplateFields(t *testing.T) {
+	for _, field := range []string{"hitl", "agent", "model"} {
+		t.Run(field, func(t *testing.T) {
+			_, err := harness.New("pi", config.RawValues{field: "unsupported"})
+			if err == nil {
+				t.Fatalf("Pi harness accepted unsupported config field %q", field)
+			}
+			if !strings.Contains(err.Error(), field) {
+				t.Fatalf("error = %q, want field name %q", err, field)
+			}
+		})
+	}
+}
+
+func TestPiHarnessConfigRejectsExplicitNullTemplate(t *testing.T) {
+	_, err := harness.New("pi", config.RawValues{"initial": nil})
+	if err == nil || !strings.Contains(err.Error(), "explicit null") {
+		t.Fatalf("explicit null template error = %v", err)
+	}
+}

package/internal/harness/pi/lifecycle_test.go

@@ -0,0 +1,69 @@
+package pi
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/harness"
+)
+
+func TestPiSetupRepoIsSideEffectFree(t *testing.T) {
+	repoPath := t.TempDir()
+	sentinelPath := filepath.Join(repoPath, "existing.txt")
+	sentinel := []byte("leave this repository unchanged")
+	if err := os.WriteFile(sentinelPath, sentinel, 0o640); err != nil {
+		t.Fatal(err)
+	}
+
+	h := newPiHarness(t)
+	if err := h.SetupRepo(context.Background(), repoPath); err != nil {
+		t.Fatalf("SetupRepo: %v", err)
+	}
+
+	data, err := os.ReadFile(sentinelPath)
+	if err != nil {
+		t.Fatalf("read sentinel: %v", err)
+	}
+	if !reflect.DeepEqual(data, sentinel) {
+		t.Fatalf("SetupRepo changed existing repository content: %q", data)
+	}
+	for _, name := range []string{"opencode.json", "opencode.jsonc", ".pi"} {
+		if _, err := os.Stat(filepath.Join(repoPath, name)); !os.IsNotExist(err) {
+			t.Fatalf("SetupRepo created %q: %v", name, err)
+		}
+	}
+}
+
+func TestPiFindSessionDoesNotDiscoverByTitle(t *testing.T) {
+	missingRepo := filepath.Join(t.TempDir(), "not-a-repository")
+	h := newPiHarness(t)
+
+	session, ok, err := h.FindSession(context.Background(), missingRepo, "PAY-101:implement")
+	if err != nil {
+		t.Fatalf("FindSession: %v", err)
+	}
+	if ok {
+		t.Fatalf("FindSession found an unrequested session: %+v", session)
+	}
+	if session != (harness.Session{}) {
+		t.Fatalf("FindSession returned session data: %+v", session)
+	}
+}
+
+func TestPiResumeUsesOnlyPersistedLaunchSpecSessionID(t *testing.T) {
+	spec := launchSpec(t)
+	spec.RepoPath = filepath.Join(t.TempDir(), "missing-ticket-environment")
+	spec.ResumeID = "session-123"
+
+	cmd, err := newPiHarness(t).BuildCommand(spec)
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+	want := []string{"--name", spec.Title, "--session-id", spec.ResumeID, spec.Prompt}
+	if !reflect.DeepEqual(cmd.Args, want) {
+		t.Fatalf("Args = %#v, want %#v", cmd.Args, want)
+	}
+}

package/internal/harness/pi/pi.go

@@ -0,0 +1,261 @@
+// Package pi is the built-in launch-time Harness adapter for the Pi coding
+// agent. Pi supplies one built-in coding agent, represented by the logical
+// relay-flow agent name "default", plus repository-owned role prompts under
+// .pi/roles. The runtime extension is installed by the user and owns report
+// parsing and delivery.
+package pi
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+)
+
+const (
+	defaultInitialPrompt = `Task system: {{taskSystem}}
+Use the {{taskSystem}} tools to read the parent ticket {{ticket}}.
+
+Your mailbox is {{mailbox}}. Read its description and comments for node instructions and feedback.`
+	defaultFeedbackPrompt = `New feedback was added to the comments section of your mailbox subtask {{mailbox}}. Read it.`
+)
+
+var promptVarPattern = regexp.MustCompile(`\{\{([^{}]*)\}\}`)
+
+var knownPromptVars = map[string]bool{
+	"taskSystem": true, "ticket": true, "workflow": true, "repo": true,
+	"node": true, "nodeType": true, "agent": true, "nodeDescription": true,
+	"nextSteps": true, "mailbox": true,
+}
+
+// Config is the adapter-owned root harnessConfig. Pi exposes no harness
+// prompt for HITL approval because approval is performed through Pi's host
+// UI by the runtime extension.
+type Config struct {
+	Initial  string `yaml:"initial"`
+	Feedback string `yaml:"feedback"`
+}
+
+// DefaultConfig is written by relay-flow init and fills omitted values when
+// configuration is loaded through the harness factory.
+func DefaultConfig() config.RawValues {
+	return config.RawValues{
+		"initial":  defaultInitialPrompt,
+		"feedback": defaultFeedbackPrompt,
+	}
+}
+
+func init() {
+	harness.Register("pi", harness.Factory{
+		DefaultConfig: DefaultConfig,
+		New: func(raw config.RawValues) (harness.Harness, error) {
+			var cfg Config
+			if err := config.DecodeStrict(raw, &cfg); err != nil {
+				return nil, fmt.Errorf("pi harnessConfig: %w", err)
+			}
+			for name, tmpl := range map[string]string{
+				"initial":  cfg.Initial,
+				"feedback": cfg.Feedback,
+			} {
+				if err := validateTemplate(tmpl); err != nil {
+					return nil, fmt.Errorf("pi harnessConfig templates.%s: %w", name, err)
+				}
+			}
+			return New(cfg), nil
+		},
+	})
+}
+
+// Harness implements harness.Harness for Pi.
+type Harness struct {
+	templates Config
+}
+
+// New returns the production Pi harness. The no-argument form uses the
+// adapter defaults; factory construction supplies an explicitly decoded
+// configuration.
+func New(cfg ...Config) *Harness {
+	if len(cfg) > 0 {
+		return &Harness{templates: cfg[0]}
+	}
+	return &Harness{templates: Config{
+		Initial:  defaultInitialPrompt,
+		Feedback: defaultFeedbackPrompt,
+	}}
+}
+
+// SetupRepo is intentionally a no-op. The relay-flow Pi runtime extension is
+// installed manually in Pi's global package settings rather than configured
+// in each repository.
+func (*Harness) SetupRepo(context.Context, string) error { return nil }
+
+// ValidateAgent accepts Pi's built-in logical agent or a repository role
+// prompt. Pi has no named-agent listing API, so custom roles are verified by
+// checking for a readable, non-empty .pi/roles/<agent>.md file.
+func (*Harness) ValidateAgent(_ context.Context, repoPath, agent string) error {
+	if _, err := resolveRolePrompt(repoPath, agent); err != nil {
+		return err
+	}
+	if _, err := exec.LookPath("pi"); err != nil {
+		return fmt.Errorf("pi: executable unavailable: %w", err)
+	}
+	return nil
+}
+
+func resolveRolePrompt(repoPath, agent string) (string, error) {
+	if agent == "default" {
+		return "", nil
+	}
+	if strings.TrimSpace(agent) == "" || strings.TrimSpace(agent) != agent || strings.ContainsAny(agent, `/\\`) || agent == "." || agent == ".." {
+		return "", fmt.Errorf("pi: invalid role %q", agent)
+	}
+	if repoPath == "" {
+		return "", fmt.Errorf("pi: role %q requires a repository path", agent)
+	}
+	root, err := filepath.Abs(repoPath)
+	if err != nil {
+		return "", fmt.Errorf("pi: resolve repository path for role %q: %w", agent, err)
+	}
+	path := filepath.Join(root, ".pi", "roles", agent+".md")
+	info, err := os.Stat(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", fmt.Errorf("pi: role %q is unavailable; expected %s", agent, path)
+		}
+		return "", fmt.Errorf("pi: inspect role %q: %w", agent, err)
+	}
+	if !info.Mode().IsRegular() {
+		return "", fmt.Errorf("pi: role %q is not a regular file: %s", agent, path)
+	}
+	contents, err := os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("pi: read role %q: %w", agent, err)
+	}
+	if strings.TrimSpace(string(contents)) == "" {
+		return "", fmt.Errorf("pi: role %q is empty: %s", agent, path)
+	}
+	return path, nil
+}
+
+// FindSession is intentionally discovery-free. Normal execution resumes only
+// the Pi session ID persisted by runtime registration.
+func (*Harness) FindSession(context.Context, string, string) (harness.Session, bool, error) {
+	return harness.Session{}, false, nil
+}
+
+// RenderPrompt renders the selected initial or feedback template and the
+// node's nudge template. HITL approval is not encoded in the prompt; the Pi
+// extension asks for approval through ctx.ui.select.
+func (h *Harness) RenderPrompt(kind harness.PromptKind, data harness.PromptData, nudgeTemplate string) (string, error) {
+	var tmpl string
+	switch kind {
+	case harness.PromptInitial:
+		tmpl = h.templates.Initial
+	case harness.PromptFeedback:
+		tmpl = h.templates.Feedback
+	default:
+		return "", fmt.Errorf("pi: unknown prompt kind %q", kind)
+	}
+	return appendPrompt(renderTemplate(tmpl, data), renderTemplate(nudgeTemplate, data)), nil
+}
+
+// BuildCommand returns the interactive Pi invocation. The runner supplies a
+// PTY for Pi's stdin/stdout; the rendered prompt is the final positional argv
+// value. A custom role adds Pi's --append-system-prompt option with the role
+// file from the registered repository. Pi 0.84.1 rejects a bare -- terminator,
+// so none is included. A non-empty ResumeID selects Pi's exact session-id
+// resume option.
+func (*Harness) BuildCommand(spec harness.LaunchSpec) (runner.Command, error) {
+	rolePath, err := resolveRolePrompt(spec.RepoPath, spec.Agent)
+	if err != nil {
+		return runner.Command{}, err
+	}
+	nextSteps, err := json.Marshal(spec.NextSteps)
+	if err != nil {
+		return runner.Command{}, fmt.Errorf("pi: marshal next steps: %w", err)
+	}
+	root, err := relayFlowHome()
+	if err != nil {
+		return runner.Command{}, err
+	}
+	env := map[string]string{
+		"RELAY_FLOW_HOME":            root,
+		"RELAY_FLOW_RUN_ID":          string(spec.RunID),
+		"RELAY_FLOW_WORKFLOW":        spec.Workflow,
+		"RELAY_FLOW_REPO":            spec.RepoName,
+		"RELAY_FLOW_TICKET":          spec.Ticket,
+		"RELAY_FLOW_NODE":            spec.Node,
+		"RELAY_FLOW_NODE_TYPE":       string(spec.NodeType),
+		"RELAY_FLOW_NUDGE_PROMPT":    spec.NudgePrompt,
+		"RELAY_FLOW_NEXT_STEPS_JSON": string(nextSteps),
+	}
+	args := []string{"--name", spec.Title}
+	if rolePath != "" {
+		args = append(args, "--append-system-prompt", rolePath)
+	}
+	if spec.ResumeID != "" {
+		args = append(args, "--session-id", spec.ResumeID)
+	}
+	args = append(args, spec.Prompt)
+	return runner.Command{
+		Executable: "pi",
+		Args:       args,
+		Env:        env,
+	}, nil
+}
+
+func relayFlowHome() (string, error) {
+	if root := os.Getenv("RELAY_FLOW_HOME"); root != "" {
+		return root, nil
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("pi: resolve relay-flow home: %w", err)
+	}
+	return filepath.Join(home, ".relay-flow"), nil
+}
+
+func validateTemplate(tmpl string) error {
+	for _, match := range promptVarPattern.FindAllStringSubmatch(tmpl, -1) {
+		if !knownPromptVars[match[1]] {
+			return fmt.Errorf("unknown template variable {{%s}}", match[1])
+		}
+	}
+	return nil
+}
+
+func renderTemplate(tmpl string, data harness.PromptData) string {
+	values := map[string]string{
+		"taskSystem":      data.TaskSystem,
+		"ticket":          data.Ticket,
+		"workflow":        data.Workflow,
+		"repo":            data.Repo,
+		"node":            data.Node,
+		"nodeType":        string(data.NodeType),
+		"agent":           data.Agent,
+		"nodeDescription": data.NodeDescription,
+		"nextSteps":       data.NextSteps,
+		"mailbox":         data.Mailbox,
+	}
+	return promptVarPattern.ReplaceAllStringFunc(tmpl, func(match string) string {
+		return values[promptVarPattern.FindStringSubmatch(match)[1]]
+	})
+}
+
+func appendPrompt(prompt, extra string) string {
+	if extra == "" {
+		return prompt
+	}
+	if prompt == "" {
+		return extra
+	}
+	return prompt + "\n\n" + extra
+}

package/internal/harness/pi/pi_test.go

@@ -0,0 +1,322 @@
+package pi
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/harness"
+	"github.com/rajpopat27/relay-flow/internal/identity"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// TestBuildCommandUsesStrictPiCLIContract executes the command returned by
+// the adapter against a fake that accepts only the installed Pi 0.84.1 launch
+// shape. The fake is intentionally an executable on PATH rather than a
+// production lookup seam: Pi availability is covered separately, while this
+// test verifies the opaque runner command and its handoff to the ticket
+// environment, including an optional repository role prompt.
+func TestBuildCommandUsesStrictPiCLIContract(t *testing.T) {
+	fakeDir, capturePath := strictPiCLI(t)
+	t.Setenv("PATH", fakeDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
+
+	base := launchSpec(t)
+	ticketEnvironment := t.TempDir()
+	nextSteps, err := json.Marshal(base.NextSteps)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantEnv := map[string]string{
+		"RELAY_FLOW_HOME":            "/var/lib/relay-flow-test",
+		"RELAY_FLOW_RUN_ID":          string(base.RunID),
+		"RELAY_FLOW_WORKFLOW":        base.Workflow,
+		"RELAY_FLOW_REPO":            base.RepoName,
+		"RELAY_FLOW_TICKET":          base.Ticket,
+		"RELAY_FLOW_NODE":            base.Node,
+		"RELAY_FLOW_NODE_TYPE":       string(base.NodeType),
+		"RELAY_FLOW_NUDGE_PROMPT":    base.NudgePrompt,
+		"RELAY_FLOW_NEXT_STEPS_JSON": string(nextSteps),
+	}
+
+	tests := []struct {
+		name     string
+		resumeID string
+		wantArgs []string
+	}{
+		{
+			name: "fresh",
+			wantArgs: []string{
+				"--name", "PAY-101:implement",
+				"first line\nsecond line",
+			},
+		},
+		{
+			name:     "resumed",
+			resumeID: "session-123",
+			wantArgs: []string{
+				"--name", "PAY-101:implement",
+				"--session-id", "session-123",
+				"first line\nsecond line",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			spec := base
+			spec.ResumeID = tt.resumeID
+			cmd, err := newPiHarness(t).BuildCommand(spec)
+			if err != nil {
+				t.Fatalf("BuildCommand: %v", err)
+			}
+			if cmd.Executable != "pi" {
+				t.Fatalf("Executable = %q, want pi", cmd.Executable)
+			}
+			if !reflect.DeepEqual(cmd.Args, tt.wantArgs) {
+				t.Fatalf("Args = %#v, want %#v", cmd.Args, tt.wantArgs)
+			}
+			if !reflect.DeepEqual(cmd.Env, wantEnv) {
+				t.Fatalf("Env = %#v, want %#v", cmd.Env, wantEnv)
+			}
+			if _, ok := cmd.Env["RELAY_FLOW_NODE_VISIT_ID"]; ok {
+				t.Fatal("command leaked internal RELAY_FLOW_NODE_VISIT_ID")
+			}
+
+			capture := runStrictPi(t, cmd, ticketEnvironment, capturePath)
+			if capture.cwd != ticketEnvironment {
+				t.Fatalf("fake Pi cwd = %q, want ticket environment %q", capture.cwd, ticketEnvironment)
+			}
+			if !reflect.DeepEqual(capture.args, tt.wantArgs) {
+				t.Fatalf("fake Pi args = %#v, want %#v", capture.args, tt.wantArgs)
+			}
+			if !reflect.DeepEqual(capture.env, wantEnv) {
+				t.Fatalf("fake Pi relay-flow env = %#v, want %#v", capture.env, wantEnv)
+			}
+		})
+	}
+}
+
+func TestBuildCommandKeepsDashPrefixedPromptPositional(t *testing.T) {
+	fakeDir, capturePath := strictPiCLI(t)
+	t.Setenv("PATH", fakeDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
+
+	spec := launchSpec(t)
+	spec.Prompt = "- summarize the current changes"
+	cmd, err := newPiHarness(t).BuildCommand(spec)
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+	want := []string{"--name", spec.Title, spec.Prompt}
+	if !reflect.DeepEqual(cmd.Args, want) {
+		t.Fatalf("Args = %#v, want %#v", cmd.Args, want)
+	}
+	capture := runStrictPi(t, cmd, t.TempDir(), capturePath)
+	if !reflect.DeepEqual(capture.args, want) {
+		t.Fatalf("fake Pi args = %#v, want %#v", capture.args, want)
+	}
+}
+
+func TestBuildCommandAddsExistingRolePrompt(t *testing.T) {
+	fakeDir, capturePath := strictPiCLI(t)
+	t.Setenv("PATH", fakeDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
+
+	spec := launchSpec(t)
+	spec.Agent = "coder"
+	rolePath := writePiRole(t, spec.RepoPath, spec.Agent, "You are the coder for relay-flow.\n")
+	cmd, err := newPiHarness(t).BuildCommand(spec)
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+	want := []string{"--name", spec.Title, "--append-system-prompt", rolePath, spec.Prompt}
+	if !reflect.DeepEqual(cmd.Args, want) {
+		t.Fatalf("Args = %#v, want %#v", cmd.Args, want)
+	}
+	capture := runStrictPi(t, cmd, t.TempDir(), capturePath)
+	if !reflect.DeepEqual(capture.args, want) {
+		t.Fatalf("fake Pi args = %#v, want %#v", capture.args, want)
+	}
+}
+
+func TestBuildCommandRejectsMissingRolePrompt(t *testing.T) {
+	spec := launchSpec(t)
+	spec.Agent = "reviewer"
+	_, err := newPiHarness(t).BuildCommand(spec)
+	if err == nil || !strings.Contains(err.Error(), ".pi/roles/reviewer.md") {
+		t.Fatalf("missing role error = %v, want role path", err)
+	}
+}
+
+func TestStrictPiCLIFakeRejectsUnsupportedLaunchFlags(t *testing.T) {
+	fakeDir, capturePath := strictPiCLI(t)
+	t.Setenv("PATH", fakeDir+string(os.PathListSeparator)+os.Getenv("PATH"))
+	t.Setenv("RELAY_FLOW_HOME", "/var/lib/relay-flow-test")
+	base := launchSpec(t)
+	ticketEnvironment := t.TempDir()
+	cmd, err := newPiHarness(t).BuildCommand(base)
+	if err != nil {
+		t.Fatalf("BuildCommand: %v", err)
+	}
+
+	for _, args := range [][]string{
+		{"--", base.Prompt},
+		{"--agent", "default", base.Prompt},
+		{"--interactive", base.Prompt},
+		{"--report", base.Prompt},
+		{"--print", base.Prompt},
+		{"--mode", "json", base.Prompt},
+		{"--mode", "rpc", base.Prompt},
+		{"--extension", "relay-flow-plugin", base.Prompt},
+		{"install", "npm:relay-flow-plugin"},
+	} {
+		bad := exec.Command("pi", args...)
+		bad.Dir = ticketEnvironment
+		bad.Env = commandEnv(cmd.Env, capturePath)
+		if err := bad.Run(); err == nil {
+			t.Fatalf("strict fake accepted unsupported args %#v", args)
+		}
+	}
+}
+
+func newPiHarness(t *testing.T) harness.Harness {
+	t.Helper()
+	h, err := harness.New("pi", nil)
+	if err != nil {
+		t.Fatalf("harness.New(pi): %v", err)
+	}
+	return h
+}
+
+func launchSpec(t *testing.T) harness.LaunchSpec {
+	t.Helper()
+	return harness.LaunchSpec{
+		RunID:       identity.NewRunID("payments", "basicFlow", "PAY-101"),
+		NodeVisitID: identity.NewNodeVisitID(),
+		RepoName:    "payments",
+		RepoPath:    t.TempDir(),
+		Workflow:    "basicFlow",
+		Ticket:      "PAY-101",
+		Node:        "implement",
+		NodeType:    workflow.NodeAgent,
+		Agent:       "default",
+		Title:       "PAY-101:implement",
+		Prompt:      "first line\nsecond line",
+		NudgePrompt: "emit the complete report",
+		NextSteps: []workflow.Route{
+			{Target: "review", When: "implementation complete"},
+			{Target: "implement", When: "needs more work"},
+		},
+	}
+}
+
+type piCapture struct {
+	cwd  string
+	args []string
+	env  map[string]string
+}
+
+func runStrictPi(t *testing.T, command runner.Command, cwd, capturePath string) piCapture {
+	t.Helper()
+	process := exec.Command(command.Executable, command.Args...)
+	process.Dir = cwd
+	process.Env = commandEnv(command.Env, capturePath)
+	if output, err := process.CombinedOutput(); err != nil {
+		t.Fatalf("strict Pi fake: %v\n%s", err, output)
+	}
+	data, err := os.ReadFile(capturePath)
+	if err != nil {
+		t.Fatalf("read strict Pi capture: %v", err)
+	}
+	fields := strings.Split(string(data), "\x00")
+	if len(fields) < 12 || fields[len(fields)-1] != "" {
+		t.Fatalf("malformed strict Pi capture: %q", data)
+	}
+	fields = fields[:len(fields)-1]
+	capture := piCapture{
+		cwd:  fields[0],
+		args: strings.Split(fields[10], "\x1f"),
+		env: map[string]string{
+			"RELAY_FLOW_HOME":            fields[1],
+			"RELAY_FLOW_RUN_ID":          fields[2],
+			"RELAY_FLOW_WORKFLOW":        fields[3],
+			"RELAY_FLOW_REPO":            fields[4],
+			"RELAY_FLOW_TICKET":          fields[5],
+			"RELAY_FLOW_NODE":            fields[6],
+			"RELAY_FLOW_NODE_TYPE":       fields[7],
+			"RELAY_FLOW_NUDGE_PROMPT":    fields[8],
+			"RELAY_FLOW_NEXT_STEPS_JSON": fields[9],
+		},
+	}
+	return capture
+}
+
+func commandEnv(values map[string]string, capturePath string) []string {
+	env := make([]string, 0, len(os.Environ())+len(values)+1)
+	for _, value := range os.Environ() {
+		key := strings.SplitN(value, "=", 2)[0]
+		if _, replaced := values[key]; replaced || key == "PI_FAKE_CAPTURE" {
+			continue
+		}
+		env = append(env, value)
+	}
+	env = append(env, "PI_FAKE_CAPTURE="+capturePath)
+	for key, value := range values {
+		env = append(env, key+"="+value)
+	}
+	return env
+}
+
+func strictPiCLI(t *testing.T) (string, string) {
+	t.Helper()
+	directory := t.TempDir()
+	executable := filepath.Join(directory, "pi")
+	capture := filepath.Join(directory, "capture")
+	const script = `#!/bin/sh
+set -eu
+
+capture=${PI_FAKE_CAPTURE:?}
+original_args=
+for arg in "$@"; do
+  if [ -n "$original_args" ]; then original_args="$original_args$(printf '\037')"; fi
+  original_args="$original_args$arg"
+done
+[ "${1:-}" = "--name" ] || exit 2
+[ "$#" -ge 3 ] || exit 2
+shift 2
+if [ "${1:-}" = "--append-system-prompt" ]; then
+  [ "$#" -ge 3 ] || exit 2
+  [ -s "$2" ] || exit 2
+  shift 2
+fi
+if [ "${1:-}" = "--session-id" ]; then
+  [ "$#" -ge 3 ] || exit 2
+  shift 2
+fi
+[ "$#" -eq 1 ] || exit 2
+
+[ -n "${RELAY_FLOW_HOME:-}" ] || exit 3
+[ -n "${RELAY_FLOW_RUN_ID:-}" ] || exit 3
+[ -n "${RELAY_FLOW_WORKFLOW:-}" ] || exit 3
+[ -n "${RELAY_FLOW_REPO:-}" ] || exit 3
+[ -n "${RELAY_FLOW_TICKET:-}" ] || exit 3
+[ -n "${RELAY_FLOW_NODE:-}" ] || exit 3
+[ -n "${RELAY_FLOW_NODE_TYPE:-}" ] || exit 3
+[ -n "${RELAY_FLOW_NEXT_STEPS_JSON:-}" ] || exit 3
+
+printf '%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000%s\000' \
+  "$PWD" "$RELAY_FLOW_HOME" "$RELAY_FLOW_RUN_ID" "$RELAY_FLOW_WORKFLOW" \
+  "$RELAY_FLOW_REPO" "$RELAY_FLOW_TICKET" "$RELAY_FLOW_NODE" "$RELAY_FLOW_NODE_TYPE" \
+  "${RELAY_FLOW_NUDGE_PROMPT:-}" "$RELAY_FLOW_NEXT_STEPS_JSON" "$original_args" > "$capture"
+`
+	if err := os.WriteFile(executable, []byte(script), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	return directory, capture
+}