Run the same program when connecting to another machine

cmd/codeaf/chatv3_host.go

@@ -13,6 +13,7 @@ import (
 	"sync/atomic"
 	"time"
 
+	"github.com/Agent-Field/codeaf/internal/buildinfo"
 	"github.com/Agent-Field/codeaf/internal/catalog"
 	"github.com/Agent-Field/codeaf/internal/config"
 	"github.com/Agent-Field/codeaf/internal/enginehost"
@@ -31,7 +32,7 @@ import (
 // ── `codeaf chat --host devbox` ─────────────────────────────────────────────
 //
 // The surface runs here and the session runs there. This file is the door: it
-// parses the destination, starts `ssh <dest> codeaf engine`, completes the
+// parses the destination, starts the matching program over ssh, completes the
 // handshake, and hands the connection to the same surface a local launch opens.
 //
 // THE PROMPT LAW, and it is the reason this whole path is shaped the way it is:
@@ -177,10 +178,8 @@ func (l *engineLink) spawn() (io.ReadWriteCloser, error) {
 	// The remote command, as the far machine's login shell will read it. The
 	// workspace is quoted because a path with a space in it is a path, and an
 	// unquoted one would arrive at `codeaf engine` as two arguments.
-	remoteCommand := "codeaf engine"
-	if l.workspace != "" {
-		remoteCommand += " --workspace " + shellQuote(l.workspace)
-	}
+	remoteCommand := hostEngineCommand(programName(), l.dest, l.workspace)
+
 	// -T because there is nothing interactive on the far end: the engine reads
 	// frames on stdin and writes them on stdout, and a pseudo-terminal in the
 	// middle would turn a newline into a carriage return and a frame into
@@ -210,6 +209,25 @@ func (l *engineLink) spawn() (io.ReadWriteCloser, error) {
 	return pipePair{r: stdout, w: stdin}, nil
 }
 
+// programName follows the executable file, including custom installation names.
+func programName() string { return codeupdate.InstallName(enginehost.ThisBinary()) }
+
+// hostEngineCommand selects on the far machine in the same ssh hop. An engine
+// failure never triggers a fallback: only absence of the requested file does.
+func hostEngineCommand(name, dest, workspace string) string {
+	args := " engine"
+	if workspace != "" {
+		args += " --workspace " + shellQuote(workspace)
+	}
+	primary := "exec " + shellQuote(name) + args
+	if name == "codeaf" {
+		return primary
+	}
+	notice := "printf '%s has no %s; using its codeaf (%s)\\n' " + shellQuote(dest) + " " + shellQuote(name) + " \"$(codeaf version)\" >&2"
+	return "if command -v " + shellQuote(name) + " >/dev/null 2>&1; then " + primary +
+		"; elif command -v codeaf >/dev/null 2>&1; then " + notice + "; exec codeaf" + args + "; else " + primary + "; fi"
+}
+
 // stderrWriter keeps the launch-time prompts visible but keeps redial output
 // inside the session's diagnostic tail. A reconnect happens while Bubble Tea
 // owns the terminal's alternate screen, so writing ssh's transient errors to
@@ -389,10 +407,8 @@ func (l *engineLink) diagnose(dest string, cause error) error {
 	}
 }
 
-const missingHostCommandText = "the program is called codeaf now (it was aforge before 2026-09-14) and must be installed on %s under that name — put it on the PATH that a non-login ssh command sees" // legacy-name
-
 func missingHostCommand(dest string) error {
-	return fmt.Errorf(missingHostCommandText, dest)
+	return fmt.Errorf("%s is not installed on %s — run %s on %s; put it on the PATH that a non-login ssh command sees", programName(), dest, codeupdate.CurlLine(enginehost.ThisBinary(), codeupdate.FollowedChannel(buildinfo.String())), dest)
 }
 
 // mentionsMissingCommand reads the far shell's own wording. The three spellings

cmd/codeaf/chatv3_host_test.go

@@ -155,7 +155,7 @@ func TestH9HostMissingCommandNamesTheCurrentInstallation(t *testing.T) {
 		}
 	}
 	got := missingHostCommand("devbox").Error()
-	for _, want := range []string{"called codeaf now", "before 2026-09-14", "installed on devbox under that name"} {
+	for _, want := range []string{"not installed on devbox", "https://agentfield.ai/get/", "non-login ssh"} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("host remedy %q does not contain %q", got, want)
 		}

cmd/codeaf/engine.go

@@ -50,12 +50,14 @@ import (
 	"path/filepath"
 	"strings"
 	"sync"
+
 	"time"
 
 	"github.com/Agent-Field/codeaf/internal/buildinfo"
 	"github.com/Agent-Field/codeaf/internal/cell"
 	"github.com/Agent-Field/codeaf/internal/config"
 	"github.com/Agent-Field/codeaf/internal/enginehost"
+	"github.com/Agent-Field/codeaf/internal/env"
 	"github.com/Agent-Field/codeaf/internal/home"
 	"github.com/Agent-Field/codeaf/internal/remote"
 	"github.com/Agent-Field/codeaf/internal/session"
@@ -299,8 +301,8 @@ func clearStaleEngineHost(workspace string) (string, error) {
 // WHICH IS OLDER IS THE BUILD MOMENT AND NOTHING ELSE, and a tie is never a
 // replacement, so two windows on two builds agree and the slot cannot go back
 // and forth. A NEWER ENGINE IS JOINED when it speaks this build's wire and
-// refused in words when it does not — the older half of that pair is this
-// binary, and the sentence names it.
+// handed to its executable when it does not. If that file cannot be used,
+// the older half of the pair is this binary, and the sentence names its update.
 func clearStaleEngineHostAs(workspace string, me engineBuild) (string, error) {
 	held, err := enginehost.Inspect(workspace)
 	if err != nil {
@@ -337,7 +339,15 @@ func clearStaleEngineHostAs(workspace string, me engineBuild) (string, error) {
 		if host.Version == remote.Version {
 			return settleCellsMode(workspace, host, me)
 		}
-		return "", &staleHost{reason: newerEngineHostSentence(hostWorkspace(host, workspace))}
+		if _, handedOff := env.Lookup(engineHandoffEnv); !handedOff && host.BuiltAt.After(me.BuiltAt) {
+			if info, err := os.Stat(host.Binary); err == nil && info.Mode().IsRegular() && info.Mode().Perm()&0111 != 0 {
+				environment := append(os.Environ(), engineHandoffEnv+"=1")
+				if err := execEngineHolder(host.Binary, os.Args, environment); err != nil {
+					return "", &staleHost{reason: newerEngineHolderSentence(host, workspace) + " (" + err.Error() + ")"}
+				}
+			}
+		}
+		return "", &staleHost{reason: newerEngineHolderSentence(host, workspace)}
 	}
 	// Too old to answer at all: it cannot say whether it is holding work, so
 	// nothing here may decide for it. Words, and the explicit stop.
@@ -350,6 +360,12 @@ func clearStaleEngineHostAs(workspace string, me engineBuild) (string, error) {
 	return olderEngineOnThisWire(workspace, held)
 }
 
+const engineHandoffEnv = "CODEAF_ENGINE_HANDOFF"
+
+func newerEngineHolderSentence(host remote.HostSelf, workspace string) string {
+	return newerEngineHostSentence(hostWorkspace(host, workspace)) + "; the holder's executable " + shellQuote(host.Binary) + " is unavailable or cannot be used"
+}
+
 // olderEngineOnThisWire is an older engine that speaks this build's protocol:
 // the ordinary road. Busy means joined, idle means asked to go.
 func olderEngineOnThisWire(workspace string, held enginehost.Holder) (string, error) {
@@ -544,9 +560,9 @@ func staleEngineHostSentence(busy bool, workspace string) string {
 	}
 	stop := engineStopWords(workspace)
 	if busy {
-		return fmt.Sprintf("engine: %s is still running an older codeaf and something is still going in it — let that finish, or run %s on %s (interrupts active turns and tasks)", name, stop, name)
+		return fmt.Sprintf("engine: %s is still running an older %s — after work finishes, close every window for --workspace %s and reopen", name, programName(), shellQuote(workspace))
 	}
-	return fmt.Sprintf("engine: %s is still holding this conversation on an older codeaf — run %s on %s (interrupts active turns and tasks)", name, stop, name)
+	return fmt.Sprintf("engine: %s is still holding this conversation on an older %s — run %s on %s", name, programName(), stop, name)
 }
 
 // unknownOlderEngineHostSentence is what a person reads when the process holding
@@ -562,8 +578,7 @@ func unknownOlderEngineHostSentence(workspace string) string {
 	if strings.TrimSpace(name) == "" {
 		name = "that machine"
 	}
-	stop := engineStopWords(workspace)
-	return fmt.Sprintf("engine: %s is holding this conversation on an older codeaf that cannot say what it is or what it is doing, and this build will not end work it cannot see — run %s on %s if you want it stopped (interrupts active turns and tasks)", name, stop, name)
+	return fmt.Sprintf("engine: %s is holding this conversation on an older %s that cannot say what it is or what it is doing — after work finishes, close every window for --workspace %s and reopen", name, programName(), shellQuote(workspace))
 }
 
 // otherProtocolEngineHostSentence is the refusal for an older engine on a wire
@@ -576,8 +591,7 @@ func otherProtocolEngineHostSentence(workspace string) string {
 	if strings.TrimSpace(name) == "" {
 		name = "that machine"
 	}
-	stop := engineStopWords(workspace)
-	return fmt.Sprintf("engine: %s is holding this conversation on a codeaf that speaks a different protocol, and something is still going in it — let that finish, or run %s on %s (interrupts active turns and tasks)", name, stop, name)
+	return fmt.Sprintf("engine: %s is holding this conversation on a %s that speaks a different protocol — after work finishes, close every window for --workspace %s and reopen", name, programName(), shellQuote(workspace))
 }
 
 // engineStopWords is the command a refusal tells a person to run: the explicit
@@ -607,15 +621,7 @@ func newerEngineHostSentence(workspace string) string {
 	if strings.TrimSpace(name) == "" {
 		name = "that machine"
 	}
-	self := enginehost.ThisBinary()
-	if strings.TrimSpace(self) == "" {
-		self = "this codeaf"
-	}
-	stop := "codeaf engine --status"
-	if workspace = strings.TrimSpace(workspace); workspace != "" {
-		stop += " --workspace " + workspace
-	}
-	return fmt.Sprintf("engine: %s is holding this conversation on a newer codeaf than %s — use the newer binary (%s on %s shows which one it is)", name, self, stop, name)
+	return fmt.Sprintf("engine: %s is holding this conversation on a newer %s — run %s update on this machine", name, programName(), programName())
 }
 
 // hostWorkspace is what the host says it is holding, and what this process asked
@@ -645,11 +651,11 @@ func busyEngineHostSentence(workspace string, waits bool) string {
 	if strings.TrimSpace(name) == "" {
 		name = "this machine"
 	}
-	note := fmt.Sprintf("this window is using an older codeaf background engine on %s; restarting one window does not update it. Attached windows count as in use. After work finishes, close every window for this workspace and reopen", name)
+	note := fmt.Sprintf("this window is using an older %s background engine on %s; restarting one window does not update it. Attached windows count as in use. After work finishes, close every window for this workspace and reopen", programName(), name)
 	if waits {
 		note += " — the engine will step aside when all windows and work are gone"
 	}
-	return note + ". Or run " + engineStopWords(workspace) + " on " + name + " (interrupts active turns and tasks); reconnect with this build"
+	return note
 }
 
 // replacedEngineHostSentence is the ONE LINE a takeover owes: which engine was

cmd/codeaf/engine_handoff_unix.go

@@ -0,0 +1,10 @@
+//go:build !windows
+
+package main
+
+import "syscall"
+
+// Exec retains the bridge's arguments and all three standard streams.
+func execEngineHolder(binary string, args, environment []string) error {
+	return syscall.Exec(binary, args, environment)
+}

cmd/codeaf/engine_handoff_windows.go

@@ -0,0 +1,9 @@
+//go:build windows
+
+package main
+
+import "fmt"
+
+func execEngineHolder(binary string, args, environment []string) error {
+	return fmt.Errorf("automatic executable handoff is unavailable on this platform")
+}

cmd/codeaf/engine_stale_test.go

@@ -269,7 +269,7 @@ func TestAnOlderEngineHoldingWorkKeepsItAndIsJoined(t *testing.T) {
 	if err != nil {
 		t.Fatalf("an older engine holding work was refused rather than joined: %v", err)
 	}
-	for _, want := range []string{"older codeaf background engine", "Attached windows count as in use", "all windows and work are gone", "interrupts active turns and tasks", engineStopWords(workspace)} {
+	for _, want := range []string{"older " + programName() + " background engine", "Attached windows count as in use", "all windows and work are gone"} {
 		if !strings.Contains(note, want) {
 			t.Fatalf("the busy line %q does not say %q", note, want)
 		}
@@ -405,7 +405,7 @@ func TestALaunchRefusesAnIncompatibleBusyEngineRatherThanFallingBack(t *testing.
 	if !errors.As(err, &refusal) {
 		t.Fatalf("the launch answered %v, want the host's own refusal", err)
 	}
-	if !strings.Contains(refusal.sentence, "different protocol") || !strings.Contains(refusal.sentence, "engine --stop") {
+	if !strings.Contains(refusal.sentence, "different protocol") || !strings.Contains(refusal.sentence, "close every window") {
 		t.Fatalf("the refusal %q does not say what is holding it and the way out", refusal.sentence)
 	}
 	// AND NOTHING WAS OPENED IN THIS PROCESS: no project tree, no journal.
@@ -431,8 +431,8 @@ func TestAnOlderBuildWithNoStampHoldingWorkIsJoined(t *testing.T) {
 	if !strings.Contains(note, "older codeaf") {
 		t.Fatalf("the notice did not say which engine this is: %q", note)
 	}
-	if !strings.Contains(note, "After work finishes, close every window") || !strings.Contains(note, "interrupts active turns and tasks") {
-		t.Fatalf("the notice does not offer a safe update and warn about explicit stop: %q", note)
+	if !strings.Contains(note, "After work finishes, close every window") || strings.Contains(note, "--stop") {
+		t.Fatalf("the notice does not offer a safe update: %q", note)
 	}
 	if !hostAnswers(workspace) || !host.waitingSaid() || host.forced() {
 		t.Fatal("a stampless older build was ended rather than joined")
@@ -509,14 +509,14 @@ func TestANewerEngineIsJoinedAndNeverReplacedByAnOlderWindow(t *testing.T) {
 func TestANewerEngineOnAnotherWireIsRefusedAndLeftAlone(t *testing.T) {
 	shortEngineHome(t)
 	workspace := "/home/somebody/api"
-	standIn(t, workspace, remote.HostSelf{Version: remote.Version + 1, Build: "tomorrow", BuiltAt: later, Workspace: workspace}, false)
+	standIn(t, workspace, remote.HostSelf{Version: remote.Version + 1, Build: "tomorrow", BuiltAt: later, Workspace: workspace, Binary: "/missing/newer-program"}, false)
 
 	_, err := clearStaleEngineHostAs(workspace, window("today", earlier))
 	var stale *staleHost
 	if !errors.As(err, &stale) {
 		t.Fatalf("a newer engine on another wire answered %v, want a refusal", err)
 	}
-	if !strings.Contains(stale.reason, "newer codeaf") || !strings.Contains(stale.reason, "codeaf engine --status --workspace "+workspace) {
+	if !strings.Contains(stale.reason, "newer ") || !strings.Contains(stale.reason, " update") {
 		t.Fatalf("the refusal does not say this binary is the older one and how to see which is newer: %q", stale.reason)
 	}
 	if !hostAnswers(workspace) {
@@ -542,7 +542,7 @@ func TestAnOlderEngineOnAnotherWireHoldingWorkIsRefusedNotKilled(t *testing.T) {
 	}
 	// AND THE COMMAND IS COPY-PASTEABLE: the folder is quoted, because a path
 	// with a space in it typed out of a sentence has to be one argument.
-	for _, want := range []string{"different protocol", "engine --stop", "--workspace " + shellQuote(workspace)} {
+	for _, want := range []string{"different protocol", "close every window", "--workspace " + shellQuote(workspace)} {
 		if !strings.Contains(stale.reason, want) {
 			t.Fatalf("the refusal %q does not say %q", stale.reason, want)
 		}
@@ -741,7 +741,7 @@ func TestAnEngineTooOldToBeAskedIsRefusedAndTheExplicitStopStillEndsIt(t *testin
 	if !errors.As(err, &stale) {
 		t.Fatalf("a too-old engine answered %v, want a refusal in words", err)
 	}
-	for _, want := range []string{"cannot say what it is", "engine --stop", "--workspace " + shellQuote(workspace)} {
+	for _, want := range []string{"cannot say what it is", "close every window", "--workspace " + shellQuote(workspace)} {
 		if !strings.Contains(stale.reason, want) {
 			t.Fatalf("the refusal %q does not say %q", stale.reason, want)
 		}
@@ -848,3 +848,77 @@ func TestEngineStatusUpgradeGuidanceMatchesAdmission(t *testing.T) {
 		})
 	}
 }
+
+// Re-execute a helper process so the production exec preserves real argv and
+// stdio rather than replacing a function with a mock.
+func TestNewerHolderHandsOffToItsExecutable(t *testing.T) {
+	if os.Getenv("CODEAF_TEST_HANDOFF_CHILD") == "1" {
+		shortEngineHome(t)
+		workspace := t.TempDir()
+		target := filepath.Join(t.TempDir(), "newer-program")
+		body := "#!/bin/sh\nprintf 'holder-exec:%s\\n' \"$CODEAF_ENGINE_HANDOFF\"\nprintf '%s\\n' \"$@\"\n"
+		if err := os.WriteFile(target, []byte(body), 0700); err != nil {
+			t.Fatal(err)
+		}
+		standIn(t, workspace, remote.HostSelf{Version: remote.Version + 1, Build: "newer", BuiltAt: later, Binary: target}, false)
+		_, err := clearStaleEngineHostAs(workspace, window("older", earlier))
+		t.Fatalf("handoff returned: %v", err)
+	}
+	cmd := exec.Command(os.Args[0], "-test.run=^TestNewerHolderHandsOffToItsExecutable$")
+	cmd.Env = append(os.Environ(), "CODEAF_TEST_HANDOFF_CHILD=1")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("handoff: %v: %s", err, out)
+	}
+	if !strings.Contains(string(out), "holder-exec:1\n-test.run=^TestNewerHolderHandsOffToItsExecutable$\n") {
+		t.Fatalf("argv or guard lost: %s", out)
+	}
+}
+
+func TestNewerHolderHandoffCannotLoopOrUseAMissingExecutable(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		mode  os.FileMode
+		guard bool
+		value string
+	}{
+		{"missing", 0, false, ""}, {"not-executable", 0600, false, ""}, {"guarded", 0700, true, "1"}, {"empty-guard", 0700, true, ""},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			shortEngineHome(t)
+			workspace := t.TempDir()
+			target := filepath.Join(t.TempDir(), "devaf")
+			if tc.mode != 0 {
+				if err := os.WriteFile(target, []byte("#!/bin/sh\nexit 9\n"), tc.mode); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if tc.guard {
+				t.Setenv(engineHandoffEnv, tc.value)
+			}
+			standIn(t, workspace, remote.HostSelf{Version: remote.Version + 1, Build: "newer", BuiltAt: later, Binary: target, Busy: true}, false)
+			_, err := clearStaleEngineHostAs(workspace, window("older", earlier))
+			if err == nil || !strings.Contains(err.Error(), target) || !strings.Contains(err.Error(), " update") || strings.Contains(err.Error(), "--stop") {
+				t.Fatalf("unsafe refusal: %v", err)
+			}
+			if !hostAnswers(workspace) {
+				t.Fatal("holder was stopped")
+			}
+		})
+	}
+}
+
+func TestChannelsShareOneWorkspaceAndTheNewerBuildWins(t *testing.T) {
+	shortEngineHome(t)
+	workspace := t.TempDir()
+	host := standIn(t, workspace, remote.HostSelf{Version: remote.Version, Build: "newer", BuiltAt: later, Binary: "/bin/devaf", Busy: true}, false)
+	for _, name := range []string{"/bin/codeaf", "/bin/devaf", "/bin/custom-af"} {
+		note, err := clearStaleEngineHostAs(workspace, engineBuild{Build: "older", BuiltAt: earlier, Binary: name})
+		if err != nil || note != "" {
+			t.Fatalf("%s could not join: %q %v", name, note, err)
+		}
+		if !hostAnswers(workspace) || host.forced() {
+			t.Fatalf("%s replaced newer holder", name)
+		}
+	}
+}