5c9897e0

feat: mux d upgrade HOST pushes this image over ssh and upgrades there

a73x 2026-09-01 15:00

Commit message

feat: mux d upgrade HOST pushes this image over ssh and upgrades there

One binary means the machine you build on already holds the image every
box needs, so the remote spelling of the upgrade verb streams
/proc/self/exe rather than fetching a release. Three foreground sshs:
a preflight whose LINE COUNT is the verdict (uname -m && command -v mux
&& mux d endpoint, the bare read verb — 1 line no mux, 2 install-only,
3 full flow, with the arch checked before any byte moves), the image
streamed into an atomic rename over the installed mux so a dropped
connection can never truncate a binary, then that box's own
'mux d upgrade' — version rule, manifest and serving check stay
daemon-side. No daemon on the box is install-only success; no mux at
all is a refusal, because a push replaces an install rather than
inventing one. --sock with HOST is refused loudly instead of silently
honoring one and dropping the other.

The usage block grew a line for [HOST], so the boot leg's absolute
refusal bound moves 15 -> 16, re-derived the way its comment derives
it. The e2e 16_push group fakes the remote behind the ssh shim and
asserts against the fake box's own files and /proc: replacement by
marker bytes, same daemon pid, exe link naming the installed path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CLAUDE.md

Old		New
@@ -271,7 +271,14 @@ own. Test fixtures in `test/`:
271	- `mux d upgrade` execs the candidate over the RUNNING daemon: same pid,	271	- `mux d upgrade` execs the candidate over the RUNNING daemon: same pid,
272	same children, same fds — so `waitpid`, the pid-named shim and agent dirs,	272	same children, same fds — so `waitpid`, the pid-named shim and agent dirs,
273	and the socket path all survive untouched, and `Server.deinit` never runs	273	and the socket path all survive untouched, and `Server.deinit` never runs
274	on that path. The manifest memfd carries only	274	on that path. `mux d upgrade HOST` is the remote spelling: a preflight ssh
		275	whose LINE COUNT is the verdict (`uname -m && command -v mux && mux d
		276	endpoint`, the bare read verb), the running image streamed into an atomic
		277	rename over the installed mux, then that box's own `mux d upgrade` — so
		278	the version rule, manifest and serving check stay daemon-side and are
		279	never reimplemented client-side. No daemon on the box is install-only
		280	success; no mux on the box is a refusal, because a push replaces an
		281	install rather than inventing one. The manifest memfd carries only
275	what cannot be rebuilt (pty fd + child pid, the VT dump and title, the	282	what cannot be rebuilt (pty fd + child pid, the VT dump and title, the
276	tracker, the QUIC arm's key bytes, the cumulative counters); scrollback,	283	tracker, the QUIC arm's key bytes, the cumulative counters); scrollback,
277	clients, delta trackers, agent channels and per-connection QUIC state are	284	clients, delta trackers, agent channels and per-connection QUIC state are

README.md

Old		New
@@ -521,6 +521,7 @@ mux d start [-d] # the daemon: in this shell, or -d to fork one and wait for
521	mux d dump [--vt] # debug: print the authoritative grid (what the screen should be)	521	mux d dump [--vt] # debug: print the authoritative grid (what the screen should be)
522	mux d stats # live sessions by name + clients each; wire stats (deltas vs snapshot bytes)	522	mux d stats # live sessions by name + clients each; wire stats (deltas vs snapshot bytes)
523	mux d upgrade # exec a newly installed binary in place; every session keeps running	523	mux d upgrade # exec a newly installed binary in place; every session keeps running
		524	mux d upgrade HOST # push THIS binary onto HOST over ssh, then upgrade its daemon the same way
524	make bench # typing-workload byte-ratio measurement	525	make bench # typing-workload byte-ratio measurement
525	```	526	```
526		527
@@ -572,6 +573,16 @@ and run`. A session in the middle of being ended (`Ctrl-\` `x`, up to half a
572	second while its shell is being hung up) refuses the upgrade with `session	573	second while its shell is being hung up) refuses the upgrade with `session
573	ending, retry` rather than carrying a shell with no master across the exec.	574	ending, retry` rather than carrying a shell with no master across the exec.
574		575
		576	The remote spelling is `mux d upgrade HOST`: one binary means the machine
		577	you build on already holds the image every box needs, so this pushes the
		578	running binary itself over ssh — it checks the arches match and finds the
		579	installed `mux` first (`command -v`, with `~/.local/bin` as the fallback),
		580	streams the image into a temp file and renames it over the install so a
		581	dropped connection can never truncate a binary, then runs that box's own
		582	`mux d upgrade`, which is everything above, there. A box with no daemon
		583	running just gets the install (exit 0, and it says so); a box with no mux
		584	at all is refused — a push replaces an install, it does not invent one.
		585
575	Coming from v0.0.1-15 or older is the one upgrade `mux d upgrade` cannot	586	Coming from v0.0.1-15 or older is the one upgrade `mux d upgrade` cannot
576	do: that daemon probes a candidate for `muxd <version>` and this binary	587	do: that daemon probes a candidate for `muxd <version>` and this binary
577	prints `mux <version>`, so it refuses. `mux d stop` then `mux d start -d`,	588	prints `mux <version>`, so it refuses. `mux d stop` then `mux d start -d`,

docs/decisions.md

+survivor's weights and the container's orientation, because nothing
+collapses so nothing re-wraps (measured in the e2e heal leg's sidecar
+pins).
+## 2026-09-01 — remote upgrade pushes the running image; the suite gets a hermetic default socket
+`mux d upgrade HOST` is the remote spelling of the local verb, and the
+design leans on ONE binary: the machine you build on already holds the
+image every box needs, so the push streams `/proc/self/exe` over ssh —
+no release fetch, no remote network, dev builds included. Chosen shapes:
+- **Preflight by line count.** One ssh runs `uname -m && command -v mux
+  && mux d endpoint` (the bare read verb — a preflight that started
+  daemons would repeat the poll bug of 2026-08). `&&` stops at the first
+  answerless step, so 1 line = no mux (refused; a push replaces an
+  install, it does not invent one), 2 = install-only (exit 0, said so),
+= full flow. The arch line is checked before any byte moves because
+  the streamed image is this machine's own.
+- **Atomic rename, remote trigger.** `cat > mux.new && chmod && mv` so a
+  dropped stream can never truncate the installed binary; then the box's
+  own `mux d upgrade` runs, keeping the version rule, manifest and
+  serving check daemon-side rather than reimplemented client-side.
+- **Rejected:** a release-tarball pull (needs remote egress, cannot ship
+  a dev build), an `--all` sweep (a shell loop away; per-host failure
+  reporting not worth designing yet), cross-arch push (refused loudly
+  instead).
+Found by the leg's RED run, fixed in e2e_lib: the suite isolated
+XDG_CONFIG/STATE/CACHE but not XDG_RUNTIME_DIR, so a leg with a bug that
+dialed the DEFAULT socket reached the developer's live daemon at
+/run/user/*/muxd.sock — the not-yet-wired `d upgrade HOST` sent it a real
+upgrade request, and only the version rule refused the exec. The lib now
+exports a scratch XDG_RUNTIME_DIR, so a stray default dial reads "nothing
+listening" instead of someone's real daemon. The usage block grew a line
+with `[HOST]`, so the boot leg's absolute refusal bound moved 15 -> 16,
+re-derived the way its comment derives it (above complaint-plus-usage,
+below the ~20-line Debug panic floor).

src/cli/main.zig

@@ @@ -5,6 +5,7 @@ @@
+// `/bin/sh` is the executable fallback when `$SHELL` is unset.
+const std = @import("std");
+const builtin = @import("builtin");
+const Server = @import("daemon").Server;
+const proto = @import("term").protocol;
+const proxy = @import("proxy");
@@ @@ -30,7 +31,8 @@ const usage = @@
+    \\  mux d proxy [--sock PATH]    (byte pump: stdio <-> session socket)
+    \\  mux d endpoint [--sock PATH] [--start] (announce QUIC port+key, then proxy)
+    \\  mux d keygen                 (write a fresh key to ~/.config/mux/key)
+    \\  mux d upgrade [HOST] [--sock PATH] (exec THIS binary over the daemon; sessions
+    \\        live. HOST: push this image there over ssh, then upgrade its daemon)
+    \\        [--allow-same-version] (strictly newer, unless this; the e2e leg's)
+    \\  mux d --version
+    \\  mux d --help
@@ @@ -143,6 +145,16 @@ const DaemonArguments = struct { @@
+    /// direct cold attach uses this flag; background polls omit it and remain
+    /// read-only.
+    start: bool = false,
+    /// `upgrade`'s one positional: the ssh host to push this image to and
+    /// upgrade there. Underscored out of generated flags; every other verb
+    /// leaves the hook cold so a bare word stays a syntax error on them.
+    _host: ?[]const u8 = null,
+    pub fn positional(self: *DaemonArguments, word: []const u8) bool {
+        if (self._cmd != .upgrade or self._host != null) return false;
+        self._host = word;
+        return true;
+    }
+};
+// These upgrade-only flags are generated by the old daemon and intentionally
@@ @@ -164,6 +176,11 @@ const UsageResponse = union(enum) { @@
+    /// The flag whose value its own type would not hold.
+    bad_value: []const u8,
+    key_without_quic,
+    /// `upgrade HOST --sock PATH`: the socket that matters on a remote
+    /// upgrade is the remote box's own default, and a --sock honored
+    /// locally while HOST is honored remotely would leave the user
+    /// believing both.
+    sock_with_host,
+};
+const DaemonInvocation = union(enum) { command: DaemonArguments, usage: UsageResponse };
@@ @@ -211,6 +228,8 @@ fn parseArgs(args: []const [:0]const u8) DaemonInvocation { @@
+    // `run` may resolve `MUX_KEY_FILE` or the default key path.
+    if (o.key != null and o.quic == null) return .{ .usage = .key_without_quic };
+    if (o._host != null and o.sock != null) return .{ .usage = .sock_with_host };
+    return .{ .command = o };
@@ @@ -231,6 +250,10 @@ fn usageExit(u: UsageResponse) u8 { @@
+            "mux d: --key without --quic has nothing to listen on; name both or neither\n",
+            .{},
+        ),
+        .sock_with_host => std.debug.print(
+            "mux d: upgrade HOST uses that box's own default socket; --sock only names a local one\n",
+            .{},
+        ),
+    return usageCode(u);
@@ @@ -257,7 +280,10 @@ pub fn main(args: []const [:0]const u8) !u8 { @@
+    // Resolve a socket path only for commands that use one. Version, help, and
+    // key generation must not depend on runtime-directory state. Resume mode
+    // receives its already-bound path through the manifest.
+    // A remote upgrade names a HOST, and the socket that matters is that
+    // box's own default; resolving a local one here would refuse the verb on
+    // a machine with no XDG_RUNTIME_DIR for no reason it could name.
+    const uses_socket = specForCmd(o._cmd).uses_socket and o.resume_fd == null and o._host == null;
+    const sock_path = if (o.sock) |s|
+        try alloc.dupe(u8, s)
+    else if (!uses_socket)
@@ @@ -283,7 +309,10 @@ pub fn main(args: []const [:0]const u8) !u8 { @@
+        .dump => return dump(alloc, sock_path, o.vt, if (o.session) |n| n.name else ""),
+        .stats => return stats(alloc, sock_path),
+        .stop => return stopCmd(alloc, sock_path),
+        .upgrade => return if (o._host) |h|
+            remoteUpgradeCmd(alloc, h, o.allow_same_version)
+        else
+            upgradeCmd(alloc, sock_path, o.allow_same_version),
+        // Proxy only pumps an existing daemon connection; it never starts a
+        // daemon. `proxy.run` reports the socket path when connection fails.
+        .proxy => return proxy.run(sock_path),
+    return 0;
+/// What the remote-upgrade preflight learned. One ssh run answers everything:
+/// `uname -m && command -v mux && mux d endpoint` — the bare endpoint verb,
+/// which never starts a daemon — and the LINE COUNT is the diagnosis, because
+/// `&&` stops at the first answerless step.
+const Preflight = union(enum) {
+    /// The ssh ran but stdout was empty: no shell spoke, nothing to trust.
+    no_answer,
+    /// `command -v mux` found nothing. Nothing to overwrite; inventing an
+    /// install location for someone else's box is not this verb's call.
+    no_mux,
+    /// The remote's `uname -m`, verbatim, for a refusal line that shows both
+    /// spellings — we stream THIS machine's image, so the words must match.
+    bad_arch: []const u8,
+    /// mux is installed at `path`; `daemon_up` says whether the endpoint verb
+    /// answered, i.e. whether there is a daemon to trigger after the push.
+    ready: struct { path: []const u8, daemon_up: bool },
+};
+/// `mux d upgrade HOST`: put THIS image on `host` and upgrade the daemon
+/// there — the remote spelling of the local verb, in the same three moves a
+/// hand upgrade makes. Preflight (one ssh, read), push (stream the image
+/// into an atomic rename over the installed mux), trigger (run the freshly
+/// installed binary as `d upgrade`, which makes IT the candidate and leaves
+/// the version rule, the manifest and the serving check to the machinery
+/// that already owns them). All three sshs run in the foreground with the
+/// user's own tty, like the entry dial: this is a dial the user asked for,
+/// and ssh's prompts are part of it.
+fn remoteUpgradeCmd(alloc: std.mem.Allocator, host: []const u8, allow_same: bool) !u8 {
+    // A refused write on a dead ssh must come back as BrokenPipe from the
+    // push loop below, not as SIGPIPE ending this process mid-report.
+    proxy.ignoreSigpipe();
+    const pf_argv = try handoff.upgradePreflightArgv(alloc, host);
+    defer handoff.freeArgv(alloc, pf_argv);
+    var pf = std.process.Child.init(pf_argv, alloc);
+    // stdin is EOF up front: a daemon's `endpoint` answer turns into a
+    // stdio proxy that pumps until its stdin closes, and the preflight only
+    // wants the announce line, not the pump.
+    pf.stdin_behavior = .Ignore;
+    pf.stdout_behavior = .Pipe;
+    // ssh's prompts and complaints go straight to the user; there is no
+    // wall on screen to protect during a `d` verb.
+    pf.stderr_behavior = .Inherit;
+    try pf.spawn();
+    // Drain to EOF even past the cap — a child blocked on a full pipe never
+    // exits, and wait() below would hold this process with it.
+    var pf_buf: [4096]u8 = undefined;
+    var pf_len: usize = 0;
+    while (true) {
+        var chunk: [1024]u8 = undefined;
+        const n = std.posix.read(pf.stdout.?.handle, &chunk) catch break;
+        if (n == 0) break;
+        const keep = @min(n, pf_buf.len - pf_len);
+        @memcpy(pf_buf[pf_len..][0..keep], chunk[0..keep]);
+        pf_len += keep;
+    }
+    const pf_term = try pf.wait();
+    // 255 is ssh's own exit code, distinct from any remote command's: the
+    // dial itself failed, and ssh has already said why on stderr.
+    if (pf_term == .Exited and pf_term.Exited == 255) {
+        std.debug.print("mux d upgrade: ssh to {s} failed\n", .{host});
+        return 1;
+    }
+    const local_arch = @tagName(builtin.cpu.arch);
+    const ready = switch (parsePreflight(pf_buf[0..pf_len], local_arch)) {
+        .no_answer => {
+            std.debug.print(
+                "mux d upgrade: {s}'s preflight answered nothing; not a box this can read\n",
+                .{host},
+            );
+            return 1;
+        },
+        .no_mux => {
+            std.debug.print(
+                "mux d upgrade: no mux on {s}'s PATH; install one there first — " ++
+                    "a push only replaces an install, it does not invent one\n",
+                .{host},
+            );
+            return 1;
+        },
+        .bad_arch => |arch| {
+            std.debug.print(
+                "mux d upgrade: {s} is {s} and this image is {s}; refusing to push a binary that cannot run there\n",
+                .{ host, arch, local_arch },
+            );
+            return 1;
+        },
+        .ready => |r| r,
+    };
+    const push_argv = handoff.upgradePushArgv(alloc, host, ready.path) catch |e| switch (e) {
+        error.BadTargetPath => {
+            std.debug.print(
+                "mux d upgrade: {s} answered a mux path with a quote in it ({s}); not a box this will shell at\n",
+                .{ host, ready.path },
+            );
+            return 1;
+        },
+        error.OutOfMemory => return error.OutOfMemory,
+    };
+    defer handoff.freeArgv(alloc, push_argv);
+    var push = std.process.Child.init(push_argv, alloc);
+    push.stdin_behavior = .Pipe;
+    push.stdout_behavior = .Inherit;
+    push.stderr_behavior = .Inherit;
+    try push.spawn();
+    // /proc/self/exe rather than a saved path: the bytes streamed are the
+    // image RUNNING here, the only thing "push this binary" can honestly
+    // mean, even if the file it was started from has since been replaced.
+    const streamed: bool = blk: {
+        var img = std.fs.openFileAbsolute("/proc/self/exe", .{}) catch break :blk false;
+        defer img.close();
+        var buf: [64 * 1024]u8 = undefined;
+        while (true) {
+            const n = std.posix.read(img.handle, &buf) catch break :blk false;
+            if (n == 0) break :blk true;
+            var off: usize = 0;
+            while (off < n) {
+                off += std.posix.write(push.stdin.?.handle, buf[off..n]) catch break :blk false;
+            }
+        }
+    };
+    push.stdin.?.close();
+    push.stdin = null;
+    const push_term = try push.wait();
+    if (!streamed or push_term != .Exited or push_term.Exited != 0) {
+        std.debug.print("mux d upgrade: the push to {s} did not land; nothing was replaced\n", .{host});
+        return 1;
+    }
+    if (!ready.daemon_up) {
+        std.debug.print(
+            "mux d upgrade: installed {s} at {s}:{s}; no daemon running there to upgrade\n",
+            .{ build_options.version, host, ready.path },
+        );
+        return 0;
+    }
+    const trig_argv = try handoff.upgradeTriggerArgv(alloc, host, allow_same);
+    defer handoff.freeArgv(alloc, trig_argv);
+    var trig = std.process.Child.init(trig_argv, alloc);
+    // Fully inherited: the remote `mux d upgrade` reports in its own words —
+    // the daemon's refusal reasons included — and those words are the report.
+    trig.stdin_behavior = .Inherit;
+    trig.stdout_behavior = .Inherit;
+    trig.stderr_behavior = .Inherit;
+    try trig.spawn();
+    const trig_term = try trig.wait();
+    return switch (trig_term) {
+        .Exited => |code| code,
+        else => 1,
+    };
+}
+/// Slices into `out` — the caller keeps the buffer alive as long as the result.
+fn parsePreflight(out: []const u8, want_arch: []const u8) Preflight {
+    var lines = std.mem.splitScalar(u8, out, '\n');
+    const arch = lines.next() orelse "";
+    if (arch.len == 0) return .no_answer;
+    if (!std.mem.eql(u8, arch, want_arch)) return .{ .bad_arch = arch };
+    const path = lines.next() orelse "";
+    if (path.len == 0) return .no_mux;
+    const announce = lines.next() orelse "";
+    return .{ .ready = .{ .path = path, .daemon_up = announce.len != 0 } };
+}
+/// Ask the daemon on `sock_path` to replace itself with the current binary. The
+/// candidate supplies its version and path; the running daemon decides whether
+/// the upgrade is allowed.
@@ @@ -1241,6 +1437,59 @@ test "parseArgs: subcommands and their existing flags" { @@
+    try std.testing.expect(parse(&.{ "d", "start", "--wat" }).usage == .unknown_arg);
+test "parsePreflight: the line count is the diagnosis" {
+    // Three lines: arch, the installed path, an endpoint announce — a daemon
+    // is up and the full push-then-upgrade flow applies.
+    const up = parsePreflight("x86_64\n/home/u/.local/bin/mux\nquic 1.2.3.4:1 k\n", "x86_64");
+    try std.testing.expectEqualStrings("/home/u/.local/bin/mux", up.ready.path);
+    try std.testing.expect(up.ready.daemon_up);
+    // Two lines: mux is installed but `mux d endpoint` answered nothing —
+    // push the image, skip the trigger.
+    const idle = parsePreflight("x86_64\n/usr/local/bin/mux\n", "x86_64");
+    try std.testing.expectEqualStrings("/usr/local/bin/mux", idle.ready.path);
+    try std.testing.expect(!idle.ready.daemon_up);
+    // One line: `command -v mux` found nothing — there is nothing to
+    // overwrite, and inventing an install location is not this verb's call.
+    try std.testing.expect(parsePreflight("x86_64\n", "x86_64") == .no_mux);
+    // The remote's word comes back for the refusal line, so the user reads
+    // both spellings rather than a bare "mismatch".
+    const arm = parsePreflight("aarch64\n/usr/bin/mux\n", "x86_64");
+    try std.testing.expectEqualStrings("aarch64", arm.bad_arch);
+    // Nothing at all is its own answer: the ssh ran but no shell spoke.
+    try std.testing.expect(parsePreflight("", "x86_64") == .no_answer);
+    try std.testing.expect(parsePreflight("\n", "x86_64") == .no_answer);
+}
+test "parseArgs: upgrade takes one HOST word, and only upgrade does" {
+    const r = parse(&.{ "d", "upgrade", "box" });
+    try std.testing.expect(r == .command);
+    try std.testing.expect(r.command._cmd == .upgrade);
+    try std.testing.expectEqualStrings("box", r.command._host.?);
+    // The flag still rides beside the word, in either order.
+    const f = parse(&.{ "d", "upgrade", "--allow-same-version", "box" });
+    try std.testing.expectEqualStrings("box", f.command._host.?);
+    try std.testing.expect(f.command.allow_same_version);
+    // No word means the local daemon, exactly as before.
+    try std.testing.expect(parse(&.{ "d", "upgrade" }).command._host == null);
+    // A second word is a mistake, not a second host.
+    try std.testing.expect(parse(&.{ "d", "upgrade", "box", "box2" }).usage == .unknown_arg);
+    // Every other verb still refuses a bare word: a host on `stop` would be
+    // a remote stop nobody designed.
+    try std.testing.expect(parse(&.{ "d", "stop", "box" }).usage == .unknown_arg);
+    // --sock names a LOCAL socket and HOST names another box; honoring one
+    // and dropping the other silently would leave the user believing both.
+    try std.testing.expect(parse(&.{ "d", "upgrade", "box", "--sock", "/x" }).usage == .sock_with_host);
+}
+test "parse: dump --session rides into the payload" {
+    const d = parse(&.{ "d", "dump", "--session", "b", "--sock", "/tmp/x.sock" });
+    try std.testing.expect(d == .command);

src/client/handoff.zig

+    alloc.free(argv);
+/// The one spelling of the ~/.local/bin fallback. `sshArgv` uses it as an
+/// assignment prefix on a single command; the upgrade words use it as a
+/// statement (`;`-terminated), because an assignment before `a && b` binds
+/// to `a` alone and the commands after the `&&`s would search the bare PATH.
+const local_bin_append = "PATH=\"$PATH:$HOME/.local/bin\"";
+/// ONE owner for the ssh line's shape.
+fn sshArgv(
+    alloc: std.mem.Allocator,
@@ @@ -264,8 +270,21 @@ fn sshArgv( @@
+    // round. sshd runs that shell non-login, so it never sources the profile
+    // putting ~/.local/bin on PATH. APPENDED: a fallback place to look, never a
+    // shadow over whatever `mux` the remote PATH already resolves.
+    const word = try std.fmt.allocPrint(alloc, local_bin_append ++ " {s}", .{remote});
+    defer alloc.free(word);
+    return sshArgvWord(alloc, host, batch_opt, word);
+}
+/// The assembly half of `sshArgv`: `word` is the finished remote word,
+/// PATH fallback already spelled. Split out so the upgrade words — compound
+/// statements whose fallback must be a statement, not an assignment prefix —
+/// share the argv shape without a second spelling of it.
+fn sshArgvWord(
+    alloc: std.mem.Allocator,
+    host: []const u8,
+    batch_opt: []const []const u8,
+    word: []const u8,
+) ![]const []const u8 {
+    var argv: [7][]const u8 = undefined;
+    argv[0] = "ssh";
+    @memcpy(argv[1 .. 1 + batch_opt.len], batch_opt);
+    };
+/// The remote-upgrade preflight: one ssh whose LINE COUNT is the verdict.
+/// `&&` stops at the first answerless step, so one line means no mux on the
+/// remote PATH, two means mux with no daemon, three means a daemon is up —
+/// and line one is `uname -m`, checked before any bytes move, because the
+/// push streams the local machine's own image. The bare endpoint verb, never
+/// `--start`: a read must not start a daemon (the invariant `recipeFor`'s
+/// polls live by), and an upgrade preflight is a read.
+pub fn upgradePreflightArgv(alloc: std.mem.Allocator, host: []const u8) ![]const []const u8 {
+    const word = local_bin_append ++ "; uname -m && command -v mux && mux d endpoint";
+    return sshArgvWord(alloc, host, &.{}, word);
+}
+/// The push: land the streamed image beside the installed mux, then rename
+/// over it. Atomic on purpose — a connection dropped mid-stream must never
+/// leave a truncated binary at the installed path, and the running daemon
+/// keeps its old inode undisturbed. `target` came off the remote's own
+/// `command -v`; a single quote in it means something is lying, and this
+/// refuses rather than escapes.
+pub fn upgradePushArgv(
+    alloc: std.mem.Allocator,
+    host: []const u8,
+    target: []const u8,
+) error{ BadTargetPath, OutOfMemory }![]const []const u8 {
+    if (std.mem.indexOfScalar(u8, target, '\'') != null) return error.BadTargetPath;
+    const word = try std.fmt.allocPrint(
+        alloc,
+        local_bin_append ++ "; cat > '{s}.new' && chmod 755 '{s}.new' && mv '{s}.new' '{s}'",
+        .{ target, target, target, target },
+    );
+    defer alloc.free(word);
+    return sshArgvWord(alloc, host, &.{}, word);
+}
+/// The trigger: the freshly pushed binary is now the installed mux, and
+/// running IT as `d upgrade` makes it the candidate — the daemon-side version
+/// rule, manifest and serving check need nothing new from here.
+pub fn upgradeTriggerArgv(
+    alloc: std.mem.Allocator,
+    host: []const u8,
+    allow_same: bool,
+) ![]const []const u8 {
+    return sshArgv(alloc, host, false, if (allow_same)
+        "mux d upgrade --allow-same-version"
+    else
+        "mux d upgrade");
+}
+/// The announce line for `ep` at `path`: mode 0600, parents created, immediate
+/// parent tightened to 0700 — the key travels in this file. OVERWRITES, unlike
+/// `xdg.writeNewKey`: everything here is re-derivable from one ssh.
+    }, quiet.asked_argv);
+test "upgradePreflightArgv: one run, three answers, and the line count is the verdict" {
+    const argv = try upgradePreflightArgv(std.testing.allocator, "user@box");
+    defer freeArgv(std.testing.allocator, argv);
+    // STATEMENT-form PATH, not the assignment-prefix `recipeFor` uses: an
+    // assignment before `uname` would bind to `uname` alone, and the two
+    // commands after the `&&`s — the ones that actually need ~/.local/bin —
+    // would search the bare non-login PATH. The bare endpoint verb, never
+    // `--start`: a preflight that started daemons would undo every remote
+    // `mux d stop` the moment someone upgraded.
+    try expectArgv(&.{
+        "ssh",
+        "user@box",
+        "PATH=\"$PATH:$HOME/.local/bin\"; uname -m && command -v mux && mux d endpoint",
+    }, argv);
+}
+test "upgradePushArgv: the image lands beside the target and renames over it" {
+    const argv = try upgradePushArgv(std.testing.allocator, "user@box", "/home/u/.local/bin/mux");
+    defer freeArgv(std.testing.allocator, argv);
+    // `.new` then `mv`: the rename is atomic, so a connection dropped
+    // mid-stream never leaves a truncated binary at the installed path, and
+    // a running daemon keeps its old inode undisturbed.
+    try expectArgv(&.{
+        "ssh",
+        "user@box",
+        "PATH=\"$PATH:$HOME/.local/bin\"; cat > '/home/u/.local/bin/mux.new'" ++
+            " && chmod 755 '/home/u/.local/bin/mux.new'" ++
+            " && mv '/home/u/.local/bin/mux.new' '/home/u/.local/bin/mux'",
+    }, argv);
+}
+test "upgradePushArgv: a quote in the target is refused, not escaped" {
+    // The path came off the remote's own `command -v` — a quote in it means
+    // something is lying, and quoting games on a remote shell are not a
+    // fight worth winning.
+    try std.testing.expectError(
+        error.BadTargetPath,
+        upgradePushArgv(std.testing.allocator, "box", "/tmp/it's/mux"),
+    );
+}
+test "upgradeTriggerArgv: the freshly installed mux is the candidate, flag and all" {
+    const bare = try upgradeTriggerArgv(std.testing.allocator, "user@box", false);
+    defer freeArgv(std.testing.allocator, bare);
+    try expectArgv(&.{
+        "ssh",
+        "user@box",
+        "PATH=\"$PATH:$HOME/.local/bin\" mux d upgrade",
+    }, bare);
+    const same = try upgradeTriggerArgv(std.testing.allocator, "user@box", true);
+    defer freeArgv(std.testing.allocator, same);
+    try expectArgv(&.{
+        "ssh",
+        "user@box",
+        "PATH=\"$PATH:$HOME/.local/bin\" mux d upgrade --allow-same-version",
+    }, same);
+}
+test "recipeFor: a batch recipe cannot prompt, an interactive one still can" {
+    const alloc = std.testing.allocator;
+    // The poller's and `mux hosts`'s recipe. Two hosts, because the flag

test/e2e.sh

Old		New
@@ -105,7 +105,7 @@ command -v python3 > /dev/null 2>&1 \|\| {
105	E2E_DIR=$(dirname "$0")	105	E2E_DIR=$(dirname "$0")
106	. "$E2E_DIR/e2e_lib.sh"	106	. "$E2E_DIR/e2e_lib.sh"
107		107
108	E2E_GROUPS='01_boot 02_predict 03_side 04_handoff 05_session 06_web 07_wallcli 08_mouse 09_hosts 10_agent 11_select 12_panes 13_birth 14_upgrade 15_askpass'	108	E2E_GROUPS='01_boot 02_predict 03_side 04_handoff 05_session 06_web 07_wallcli 08_mouse 09_hosts 10_agent 11_select 12_panes 13_birth 14_upgrade 15_askpass 16_push'
109	# The groups that cannot stand alone, and what they need. E2E_ONLY refuses	109	# The groups that cannot stand alone, and what they need. E2E_ONLY refuses
110	# these by name rather than running them: a group whose fixtures are	110	# these by name rather than running them: a group whose fixtures are
111	# missing does not fail, it passes having tested something else — and a	111	# missing does not fail, it passes having tested something else — and a
@@ -170,8 +170,8 @@ done
170	# one of those and adds a convergence point would be pinning a fact every	170	# one of those and adds a convergence point would be pinning a fact every
171	# leg above already establishes.	171	# leg above already establishes.
172		172
173	[ "$OK_COUNT" = "101" ] \|\| {	173	[ "$OK_COUNT" = "105" ] \|\| {
174	echo "e2e FAIL: $OK_COUNT scenario checkpoints ran, the pin says 101 —"	174	echo "e2e FAIL: $OK_COUNT scenario checkpoints ran, the pin says 105 —"
175	echo " a scenario was added (update the pin) or silently lost"	175	echo " a scenario was added (update the pin) or silently lost"
176	exit 1	176	exit 1
177	}	177	}

test/e2e_01_boot.sh

Old		New
@@ -439,11 +439,12 @@ refuse() {
439	# one is measured from the no-args usage path, which is NOT one of the	439	# one is measured from the no-args usage path, which is NOT one of the
440	# paths it bounds: if usage printing ever ballooned, the bound would	440	# paths it bounds: if usage printing ever ballooned, the bound would
441	# balloon with it and quietly stop catching a panic. The absolute one	441	# balloon with it and quietly stop catching a panic. The absolute one
442	# cannot drift, and 15 sits above any plausible complaint-plus-usage	442	# cannot drift, and 16 sits above any plausible complaint-plus-usage
443	# and below the ~20 lines of the smallest Debug panic.	443	# (the block is 15 lines since `upgrade HOST` joined it) and below the
		444	# ~20 lines of the smallest Debug panic.
444	_usage_lines=$("$MUX" d 2>&1 \| wc -l)	445	_usage_lines=$("$MUX" d 2>&1 \| wc -l)
445	_lines=$(wc -l < "$OUT.q")	446	_lines=$(wc -l < "$OUT.q")
446	{ [ "$_lines" -le $((_usage_lines + 2)) ] && [ "$_lines" -le 15 ]; } \|\| {	447	{ [ "$_lines" -le $((_usage_lines + 2)) ] && [ "$_lines" -le 16 ]; } \|\| {
447	echo "e2e FAIL: mux d start $* answered with more than a message:"; cat "$OUT.q"; exit 1;	448	echo "e2e FAIL: mux d start $* answered with more than a message:"; cat "$OUT.q"; exit 1;
448	}	449	}
449	}	450	}

test/e2e_16_push.sh

@@ @@ -0,0 +1,168 @@ @@
+# shellcheck shell=sh
+# e2e_16_push.sh — sourced by test/e2e.sh after e2e_lib.sh. Scenarios run in
+# the order they stand in; see the lib's header for what this file may assume
+# and what it must register.
+# `mux d upgrade HOST` — the push flow: one preflight ssh whose line count is
+# the verdict, the image streamed over a second ssh into an atomic rename,
+# and the freshly installed binary run as `d upgrade` over a third. The
+# "remote" is this box behind the ssh shim: a HOME of its own, a bare PATH,
+# and the one mux it has installed at ~/.local/bin. Every claim the flow
+# makes about that box is asserted against the fake box's own files and
+# /proc, never against the pusher's report.
+PUSHROOT="${TMPDIR:-/tmp}/mux-e2e-push-$$"
+defer_rm "$PUSHROOT"
+# The box that has no mux at all, for the refusal that must invent nothing.
+PUSHBARE="${TMPDIR:-/tmp}/mux-e2e-pushbare-$$"
+defer_rm "$PUSHBARE"
+PUSHIM_DIR="${TMPDIR:-/tmp}/mux-e2e-pushshim-$$"
+defer_rm "$PUSHIM_DIR"
+PUSHSOCK="$PUSHROOT/run/muxd.sock"
+defer_sock "$PUSHSOCK"
+PUSHINST="$PUSHROOT/.local/bin/mux"
+mkdir -p "$PUSHROOT/.local/bin" "$PUSHROOT/run" "$PUSHROOT/state" \
+    "$PUSHBARE" "$PUSHIM_DIR/fakebin"
+# The shim IS ssh as far as the pusher can tell (e2e_04 explains that
+# contract), and here it also IS the remote box: it swaps in the fake box's
+# HOME, xdg dirs and a BARE PATH before handing the word to a shell. Bare,
+# because the build's bin directory leads this suite's PATH, and a
+# `command -v mux` that found the build's binary would be the fake remote
+# answering with the pusher's own install. The word's appended
+# `$HOME/.local/bin` is then the only place a mux can be found — which is
+# exactly the claim the appended fallback makes. PUSHIM_HOME picks the box
+# per scenario; PUSHIM_PATH lets the arch scenario front a lying uname.
+ssh_shim_head "$PUSHIM_DIR/ssh"
+cat >> "$PUSHIM_DIR/ssh" <<'SHIM'
+shift
+HOME="${PUSHIM_HOME:?}" \
+XDG_RUNTIME_DIR="${PUSHIM_HOME:?}/run" \
+XDG_STATE_HOME="${PUSHIM_HOME:?}/state" \
+XDG_CONFIG_HOME="${PUSHIM_HOME:?}/config" \
+XDG_CACHE_HOME="${PUSHIM_HOME:?}/cache" \
+SHELL=/bin/bash \
+PATH="${PUSHIM_PATH:-/usr/bin:/bin}" \
+    exec /bin/sh -c "$*"
+SHIM
+chmod +x "$PUSHIM_DIR/ssh"
+PPATH="$PUSHIM_DIR:$PATH"
+# The installed mux the push must replace: the real binary with a marker
+# byte tail, so "replaced" and "untouched" are each one cmp/tail away and
+# neither can pass by the two files having been identical all along. The
+# appended tail changes no ELF header, so the marked copy still runs.
+cp "$MUX_ELF" "$PUSHINST"
+printf 'MUXOLDIMG' >> "$PUSHINST"
+chmod 755 "$PUSHINST"
+# --- refusal: a box with no mux gets nothing invented onto it ------------
+if PUSHIM_HOME="$PUSHBARE" PATH="$PPATH" \
+    "$MUX" d upgrade pushbox > "$OUT.push_nomux" 2>&1; then
+    echo "e2e FAIL: push onto a box with no installed mux exited 0:"
+    cat "$OUT.push_nomux"
+    exit 1
+fi
+grep -q "no mux" "$OUT.push_nomux" || {
+    echo "e2e FAIL: the no-mux refusal never said so; the capture holds:"
+    cat "$OUT.push_nomux"
+    exit 1
+}
+# Refused means refused: the bare box gained no ~/.local/bin/mux.
+[ ! -e "$PUSHBARE/.local/bin/mux" ] || {
+    echo "e2e FAIL: the no-mux refusal installed a mux anyway"
+    exit 1
+}
+ok "d upgrade HOST refuses a box with no installed mux"
+# --- refusal: an arch mismatch is caught before any byte moves -----------
+printf '#!/bin/sh\necho armv7l\n' > "$PUSHIM_DIR/fakebin/uname"
+chmod +x "$PUSHIM_DIR/fakebin/uname"
+if PUSHIM_HOME="$PUSHROOT" PUSHIM_PATH="$PUSHIM_DIR/fakebin:/usr/bin:/bin" \
+    PATH="$PPATH" "$MUX" d upgrade pushbox > "$OUT.push_arch" 2>&1; then
+    echo "e2e FAIL: push onto a mismatched arch exited 0:"
+    cat "$OUT.push_arch"
+    exit 1
+fi
+# Both spellings in the refusal, so the reader sees the mismatch rather
+# than being told one exists.
+grep -q "armv7l" "$OUT.push_arch" || {
+    echo "e2e FAIL: the arch refusal never named the remote's word; capture:"
+    cat "$OUT.push_arch"
+    exit 1
+}
+[ "$(tail -c 9 "$PUSHINST")" = "MUXOLDIMG" ] || {
+    echo "e2e FAIL: the arch refusal touched the installed binary"
+    exit 1
+}
+ok "d upgrade HOST refuses an arch mismatch before pushing"
+# --- push with no daemon: install lands, nothing starts, exit 0 ----------
+if ! PUSHIM_HOME="$PUSHROOT" PATH="$PPATH" \
+    "$MUX" d upgrade pushbox > "$OUT.push_idle" 2>&1; then
+    echo "e2e FAIL: push onto a daemonless box failed; the capture holds:"
+    cat "$OUT.push_idle"
+    exit 1
+fi
+grep -q "no daemon" "$OUT.push_idle" || {
+    echo "e2e FAIL: the daemonless push never said the daemon step was skipped:"
+    cat "$OUT.push_idle"
+    exit 1
+}
+# The install is byte-for-byte this build's image: marker gone, cmp clean.
+cmp -s "$PUSHINST" "$MUX_ELF" || {
+    echo "e2e FAIL: after a daemonless push the installed mux is not this image"
+    exit 1
+}
+# A push is not a start: nothing may be listening on the fake box's socket.
+[ ! -S "$PUSHSOCK" ] || {
+    echo "e2e FAIL: the daemonless push left a socket — something started a daemon"
+    exit 1
+}
+ok "d upgrade HOST with no remote daemon installs and starts nothing"
+# --- push with a live daemon: same pid, new image, still serving ---------
+# Marked again so this scenario, like the last, proves a replacement and
+# not a coincidence of identical files.
+printf 'MUXOLDIMG' >> "$PUSHINST"
+# The remote daemon runs FROM the installed path with the fake box's own
+# environment, exactly as a box that booted one would hold it. Foreground
+# `d start` IS the daemon, so $! is the daemon's pid — the one the exec
+# must keep.
+env HOME="$PUSHROOT" XDG_RUNTIME_DIR="$PUSHROOT/run" \
+    XDG_STATE_HOME="$PUSHROOT/state" XDG_CONFIG_HOME="$PUSHROOT/config" \
+    XDG_CACHE_HOME="$PUSHROOT/cache" SHELL=/bin/bash \
+    "$PUSHINST" d start > "$OUT.pushd.log" 2>&1 &
+PUSHDPID=$!
+defer_kill "$PUSHDPID"
+wait_sock "$PUSHSOCK" "$OUT.pushd.log" "push-target daemon"
+if ! PUSHIM_HOME="$PUSHROOT" PATH="$PPATH" \
+    "$MUX" d upgrade pushbox --allow-same-version > "$OUT.push_live" 2>&1; then
+    echo "e2e FAIL: push onto a live daemon failed; the capture holds:"
+    cat "$OUT.push_live"
+    cat "$OUT.pushd.log"
+    exit 1
+fi
+# The remote trigger's own verdict, relayed verbatim through the ssh.
+grep -q "upgraded to" "$OUT.push_live" || {
+    echo "e2e FAIL: the live push never reported the daemon upgrade:"
+    cat "$OUT.push_live"
+    exit 1
+}
+# The OS's account, not the daemon's: same pid, and its exe link names the
+# installed path with no ' (deleted)' tail — the exec adopted the NEW inode
+# at that path, rather than the old one riding out a rename.
+kill -0 "$PUSHDPID" 2>/dev/null || {
+    echo "e2e FAIL: the daemon pid died across the push upgrade"
+    exit 1
+}
+[ "$(readlink "/proc/$PUSHDPID/exe")" = "$PUSHINST" ] || {
+    echo "e2e FAIL: /proc/$PUSHDPID/exe is $(readlink "/proc/$PUSHDPID/exe"), not $PUSHINST"
+    exit 1
+}
+cmp -s "$PUSHINST" "$MUX_ELF" || {
+    echo "e2e FAIL: after the live push the installed mux is not this image"
+    exit 1
+}
+ok "d upgrade HOST pushes the image and the remote daemon execs it in place"