fix: harden ssh script shell compatibility

docs/reference/cli.md

@@ -141,7 +141,7 @@ exec /root/unidesk/scripts/tran "$@"
 
 主 server 上的人工/Codex 分布式敏捷操作必须直接写 `tran ...`，不要在 Codex 工具调用里退回完整 `bun scripts/cli.ts ssh ...` 前缀。例如 `tran D601:/home/ubuntu/workspace/hwlab-dev git status --short --branch`、`tran D601:k3s kubectl get pods -n hwlab-dev` 或 `tran D601:k3s:hwlab-dev:hwlab-cloud-web/tmp pwd`。CLI 命令参考和需要跨机器复制的脚本为了说明稳定入口，可以保留完整 `bun scripts/cli.ts ssh ...` 形式；`tran` 是主 server 本机操作纪律，不作为远端 provider 或 CI/CD 的前置依赖。
 
-`tran` 同样遵守 route/operation 解析器；route 后面的第一个 token 不是原生 ssh 命令字符串。不要写 `tran G14:/root/hwlab sh -lc '...'`，因为 `sh` 会被解析为 stdin script helper 的别名，`-lc` 会变成不受支持的 script 选项。带变量展开、管道、重定向或多条命令的远端逻辑，默认使用 `tran G14:/root/hwlab script <<'SCRIPT'`；默认 `script` 走目标节点 `/bin/sh`，并继承 provider-gateway/G14 已长期化的 proxy 环境。需要临时单步执行一行远端 shell 逻辑、且不想先创建脚本文件或 heredoc 时，优先使用 `tran G14:/root/hwlab script -- 'sed -n "1,20p" a && sed -n "1,20p" b'`，CLI 会把单个字符串放进目标节点的 `sh -c`，第二个 `sed`、管道和重定向都会留在远端；等价 `shell '<command>'` 仍保留为显式 shell operation。`script --` 后跟多个 token 时保持 direct argv，例如 `tran G14:/root/hwlab script -- sed -n '1,20p' AGENTS.md`。只有脚本确实使用 `pipefail`、数组、`[[ ... ]]` 等 bash 专有语义时才加 `--shell bash`，不能把 `--shell bash` 当作 proxy 修复手段。单进程命令才直接写成 argv，例如 `tran G14:/root/hwlab git status --short --branch`。遇到分布式开发摩擦时，优先补强 `tran` 的 route/operation、stdin helper 或目标节点环境，并把稳定解法写回长期参考文档，不要退回多层 shell 字符串拼接。
+`tran` 同样遵守 route/operation 解析器；route 后面的第一个 token 不是原生 ssh 命令字符串。不要写 `tran G14:/root/hwlab sh -lc '...'`，因为 `sh` 会被解析为 stdin script helper 的别名，`-lc` 会变成不受支持的 script 选项。带变量展开、管道、重定向或多条命令的远端逻辑，默认使用 `tran G14:/root/hwlab script <<'SCRIPT'`；默认 `script` 走目标节点 `/bin/sh`，并继承 provider-gateway/G14 已长期化的 proxy 环境。需要临时单步执行一行远端 shell 逻辑、且不想先创建脚本文件或 heredoc 时，优先使用 `tran G14:/root/hwlab script -- 'sed -n "1,20p" a && sed -n "1,20p" b'`，CLI 会把单个字符串放进目标节点的 `sh -c`，第二个 `sed`、管道和重定向都会留在远端；等价 `shell '<command>'` 仍保留为显式 shell operation。`script` 和 `shell` helper 会在用户 shell 文本前注入一个极小的 POSIX 兼容 `printf` wrapper，使 `printf "--- section ---\n"` 这类高频排障分隔标题在 dash/sh 与 bash 下行为一致；direct argv 形态不注入该 wrapper。`script --` 后跟多个 token 时保持 direct argv，例如 `tran G14:/root/hwlab script -- sed -n '1,20p' AGENTS.md`。只有脚本确实使用 `pipefail`、数组、`[[ ... ]]` 等 bash 专有语义时才加 `--shell bash`，不能把 `--shell bash` 当作 proxy 修复手段。单进程命令才直接写成 argv，例如 `tran G14:/root/hwlab git status --short --branch`。遇到分布式开发摩擦时，优先补强 `tran` 的 route/operation、stdin helper 或目标节点环境，并把稳定解法写回长期参考文档，不要退回多层 shell 字符串拼接。
 
 本地 shell 运算符不是 `tran` 可以拦截的内容。`tran G14:/root/hwlab sed -n '1,20p' AGENTS.md && sed -n '1,20p' docs/reference/g14.md` 会先由 master server 的本地 shell 拆成两个命令，只有第一个 `sed` 进入 G14，第二个 `sed` 会在 master server 当前目录执行。需要把两个命令都放到目标节点时，必须写成 `tran G14:/root/hwlab script -- 'sed -n "1,20p" AGENTS.md && sed -n "1,20p" docs/reference/g14.md'`，或者用 `tran G14:/root/hwlab script <<'SCRIPT'` 把多行脚本送到远端。
 
@@ -201,7 +201,7 @@ printf 'import sys\nprint(sys.argv)\n' | bun scripts/cli.ts ssh D601 py foo '--b
 
 `ssh <providerId> py` 的附加参数是脚本参数，不是 Python 解释器参数；如需 `-m`、`-X` 或多条 shell 命令，仍使用原始远端命令入口。为了保证 CLI 输出及时可见，helper 固定采用“临时文件 + `python3 -u`”模式；provider 命令模式不分配 TTY，因此脚本内容不应被远端回显。
 
-如果远端逻辑需要 shell 特性，不要再把整段脚本作为原生 ssh-like 命令字符串传入。正式入口是 `bun scripts/cli.ts ssh D601 script`，脚本正文从 stdin 进入；CLI 会把本地 stdin 直接送到远端 `sh -s --`，`--shell bash` 可切换为 bash，`--` 后的内容会作为脚本参数传入。临时单步执行优先用 quoted heredoc；只有命令很短、明确希望一行内完成时才用 `script -- '<command && command>'`，它会把单个字符串按远端 shell one-liner 执行且不等待 stdin；复用脚本时才用 `< script.sh` 文件重定向。`script -- <多个 argv>` 仍是 direct argv，不经过远端 shell，适合 `script -- sed -n '1,20p' file`。典型用法：
+如果远端逻辑需要 shell 特性，不要再把整段脚本作为原生 ssh-like 命令字符串传入。正式入口是 `bun scripts/cli.ts ssh D601 script`，脚本正文从 stdin 进入；CLI 会把本地 stdin 直接送到远端 `sh -s --`，`--shell bash` 可切换为 bash，`--` 后的内容会作为脚本参数传入。`script`/`shell` helper 会在用户脚本文本前注入兼容前缀，让 `printf "--- section ---\n"` 这类分隔标题不再因目标 `/bin/sh` 方言失败；已有 `printf '%s\n' value`、`printf -- ...` 和 bash 的 `printf -v` 仍按原语义工作。临时单步执行优先用 quoted heredoc；只有命令很短、明确希望一行内完成时才用 `script -- '<command && command>'`，它会把单个字符串按远端 shell one-liner 执行且不等待 stdin；复用脚本时才用 `< script.sh` 文件重定向。`script -- <多个 argv>` 仍是 direct argv，不经过远端 shell，适合 `script -- sed -n '1,20p' file`。典型用法：
 
 ```bash
 cat <<'SCRIPT' | bun scripts/cli.ts ssh D601 script --shell bash -- alpha