Module helper_install 

Installing AgentMux’s helper (agentmux-remote) on an SSH host, for durable sessions (spec §6.2 of SPEC_REMOTE_TERMINALS_AND_DURABLE_SESSIONS_2026_10_02.md).

1. Probe the host over the pane’s own ssh: uname -sm, and whether this version’s helper is already at ~/.agentmux-remote/bin/<version>/.
2. Get the matching static build from this package, which carries all four (tools/remote/<target>/, spec §9.1; on macOS the Linux builds sit in Contents/Resources/remote/<target>/). A developer can point AGENTMUX_REMOTE_HELPER_DIR at their own builds (scripts/build-remote-helpers.sh writes the same layout).
3. Upload it over that ssh (cat > a temp file in an owner-only folder; no scp or sftp needed on the host), check its hash there, then chmod 700 and move it into place.

Every remote script runs under sh -c '...', so it works whatever the user’s login shell is.

Structs

Probe

What a probe found.

Constants

HELPER_FILE 🔒

Functions

asset_name

The flat name a build had as a release asset, agentmux-remote-<version>-<target>. Still accepted in AGENTMUX_REMOTE_HELPER_DIR beside the packaged layout.

candidate_paths 🔒

The paths to try for target, in order: dev_dir (AGENTMUX_REMOTE_HELPER_DIR) alone when it is set, else this package’s.

ensure

Put this version’s helper on host if it is not there (spec §6.2): probe the platform (recorded under connection for Connectors → Remotes), get the matching build (checked against the release’s hashes), upload it over ssh, check its hash there, move it in. tag names this install’s own temp file (letters, digits, -, _), so two installs on one host never touch each other’s upload. announce hears the size just before the upload, for whoever is waiting to say what is happening.

install_command

Checks the uploaded file’s hash; on a match makes it the helper, else removes it. Prints ok or mismatch <hash>.

local_build

This version’s build for target, and its hash: from AGENTMUX_REMOTE_HELPER_DIR when set (a developer’s own builds), else from this package (spec §9.1). Nothing is downloaded.

packaged_paths

Where a package keeps the build for target, relative to srv’s own folder (exe_dir): tools/remote/<target>/ beside the other bundled tools, or, in a macOS app, ../Resources/remote/<target>/, because the bundle seal only allows Mach-O code under Contents/MacOS and the Linux builds are data there.

parse_probe

Read a probe’s output.

probe_command

Prints uname -sm, then this version’s helper’s version line if it is installed and runs.

read_first 🔒

remote_dir 🔒

The helper’s folder on the host, relative to the remote home.

remove_command

Removes the helper from the host (SPEC_REMOTES_PANE_2026_10_05.md §4.9): ends every session each installed version’s daemon holds, then deletes ~/.agentmux-remote. The daemon, with no sessions left, exits on its own. Prints ok.

sh 🔒

One remote command: sh -c '<script>', single-quoted for whatever shell the user logs in with.

sha256_hex

target_for

The helper’s build target for uname -sm output (Linux x86_64, Darwin arm64, …). None for a platform without a build.

temp_name 🔒

Reads the binary from stdin into a temp file in an owner-only folder. A temp file of this install’s own (tag: the pane’s session id, letters, digits, - and _), so two panes installing on one host at once never write, check or remove each other’s upload.

upload_command