Module ssh 

shine ssh: wraps the system ssh binary to establish an interactive session that also carries a session-scoped file-transfer channel back to the local machine (see docs/ssh-local-transfer-prd.md).

Architecture, confirmed against a real host via scripts/spike-ssh-forward.sh:

• We prepend our own -R <remote-sock>:<local-forward-target> to the user’s ssh args (safe: ssh options may appear in any order before the destination).
• We replace the remote command with a wrapper that sets SHINE_SSH_SESSION/SHINE_SSH_TOKEN/SHINE_SSH_REMOTE_SOCK via env (not SetEnv/SendEnv, which most sshd configs don’t accept), then execs either the user’s original remote command or their login shell. Explicit --with/--with-secret values join that process environment.
• sshd does NOT clean up the forwarded remote socket file on disconnect (confirmed by the spike), so the wrapper registers its own trap ... EXIT to remove it.

The default remote mode is POSIX: it uses a Unix socket and a POSIX shell wrapper regardless of the local platform. --remote-shell windows is an explicit environment-forwarding-only mode: it sends a Base64-encoded PowerShell bootstrap, preferring PowerShell 7 (pwsh.exe) and falling back to Windows PowerShell (powershell.exe), and deliberately creates no transfer listener or -R forward. Locally, the POSIX path’s bind_local_listener uses a Unix socket on macOS/Linux, or loopback TCP on Windows.

Functions

broker_session_available

describe_broker_workspace

handle_local_download

handle_local_status

handle_local_upload

handle_ssh

request_direct_secrets

request_workspace_secrets