ssh-ops

There is a tool family for this, and it is better than the command

run_command "ssh user@host ..." works and is the wrong way. The ssh_* tools hold a connection open, so the second command does not pay a handshake; they return structured results instead of a blob you have to parse; and each one is its own row in the action log, which means "what did it do on that server" is answerable. A single ssh command line hides the whole session inside one row.

The shape of a session

ssh_connect    host, user, and a key or an agent
ssh_exec       one command, as many times as you need
ssh_disconnect when the work is done

ssh_list shows what is already open — check it before connecting, because a second connection to a host you are already on is a second session to clean up and a second row in everybody's w.

Disconnect when you are finished. A connection left open outlives the task, holds a session on somebody else's machine, and is exactly the residue a person has to notice and clean up by hand.

Files

ssh_upload and ssh_download rather than scp through a command. Two rules that come from the same place as everything else here:

• Check the artifact. An upload that returned ok has told you it did not throw. ssh_exec "ls -l <path>" — or better, compare a checksum — before you build anything on top of it.
• Say where it went. A file transferred and not named is a file nobody can find. ssh_list_remote is how you look before you guess a path.

Keys

ssh_keygen makes one, ssh_copy_id installs a public key on a host you can already reach with a password. Two things that are not negotiable:

• A private key is never read, never printed, and never travels through a tool argument. If a step seems to need the key material itself, that step is wrong: the tools take a path, not a secret.
• A passphrase is a credential, so the rule in your system prompt applies — do not type one into an argument. Have the person do it.

Tunnels

ssh_tunnel_local reaches a service on the remote side from here; ssh_tunnel_remote exposes something here to the far side, which is the one worth thinking twice about — it opens a way in to this desktop. Say what you are opening and why before you open it.

ssh_tunnels lists what is up and ssh_tunnel_close takes one down. Close them when the task ends, for the same reason connections get closed: a tunnel nobody remembers is a hole nobody is watching.

Scope, and why the trail protects you

Only hosts you were explicitly asked to reach. Everything you run there crosses this desktop's socket and lands on its action log, which is what makes an authorised piece of remote work defensible afterwards — and what makes reaching a host nobody named indefensible. If the scope is unclear, ask_human rather than assume.

The long ones are jobs

A deploy, a big rsync, a package install on the far side: job_start, then job_wait. A wait that times out has not cancelled the remote work — call job_wait again. Starting a second deploy because the first "timed out" is the same mistake as locally, with somebody else's server on the receiving end.